_private/qwestly-private-docs/SOC2/access-control/API-Key-Management.md

Table of Contents

API Key Management — SOC2 Evidence

Document Version: 1.0
Date: May 26, 2026
Owner: Dominick Pham, CTO
Classification: Internal Use

Executive Summary

This document defines Qwestly's API key management policy, including key creation, rotation, storage, and revocation procedures. The policy covers all third-party API keys used in production (OpenAI, LangSmith, VAPI, and similar), as well as internal service keys. It was created in response to the May 21, 2026 OpenAI key compromise incident and fills a gap in our previous credential management coverage.

SOC2 Trust Services Criteria Addressed

Criteria Control Objective Implementation Status
CC6.1 Logical and physical access controls ✅ Implemented
CC6.3 Access control systems and procedures ✅ Implemented
CC6.6 Data processing integrity ✅ Implemented
CC7.1 System monitoring ✅ Implemented

Policy Details

Scope

This policy applies to all API keys and secrets used by Qwestly's production and staging environments, including:

  • AI provider keys — OpenAI API keys, LangSmith API keys, Anthropic API keys (if applicable)
  • Voice/telephony keys — VAPI API keys
  • Infrastructure keys — Supabase service role keys, Auth0 API keys, Vercel deployment tokens
  • Third-party service keys — Any key authenticating Qwestly's production systems with external providers

Key Rotation Schedule

Key Type Rotation Frequency Trigger Events
Production API keys (OpenAI, VAPI, etc.) Every 90 days Compromise suspicion, vendor notification, employee offboarding with access
Staging/Dev API keys Every 90 days (or on production rotation) Same as production
Infrastructure secrets (DB creds, service roles) Every 180 days Employee offboarding, privilege change
Incident-triggered Immediate Any confirmed or suspected leak

90 days was chosen as the standard rotation window — it aligns with SOC2 common practice, is frequent enough to limit blast radius, and is practical to automate without being onerous for a small team.

Separation of Environments

  • Production and staging environments must use separate API keys
  • No production key should be stored in a .env file checked into any repository
  • Dev/local keys should be scoped to the minimum necessary permissions (e.g., OpenAI usage limits, restricted models)

Storage

  • All production API keys are stored in Vercel Environment Variables (for Vercel-deployed services)
  • For non-Vercel services: keys are stored in the service's secure configuration (e.g., VAPI dashboard, Supabase)
  • No production API keys are stored in code, .env files in repos, or shared via unsecured channels
  • 1Password is used for secure backup storage of all API keys

Rotation Procedure

  1. Generate new key in the provider's dashboard
  2. Verify the new key works in the target environment (staging first when possible)
  3. Replace the old key value in Vercel environment variables or equivalent
  4. Redeploy affected services
  5. Verify production functionality with the new key
  6. Revoke the old key in the provider's dashboard
  7. Log the rotation in the change log

Incident-Triggered Rotation

If a key is suspected compromised:

  1. Rotate immediately — do not wait for the scheduled window
  2. Follow the full rotation procedure above
  3. Document the incident (see incident response docs)
  4. Assess whether other keys or services may be affected

Implementation Details

Current Key Inventory

Service Key Type Storage Location Rotation Due Notes
OpenAI Production API key Vercel env vars, VAPI dashboard Last rotated: May 21, 2026 (compromise-triggered) Separate keys for prod and test
LangSmith API key Vercel env vars Last rotated: May 21, 2026 —
VAPI OpenAI key (configured in VAPI) VAPI dashboard Last rotated: May 21, 2026 Usage depends on OpenAI key
Vercel Deployment token Vercel env vars (repo secret for CI) Expires: May 28, 2027 (1-year) Token: vcp_...Pg5 (last 4 chars), created May 28, 2026

Note: The inventory above was rotated on May 21, 2026 in response to a compromise. The next scheduled rotation is August 19, 2026 (~90 days).

Monitoring

  • OpenAI sends email notifications for suspected key compromises (as experienced May 21, 2026)
  • Any key compromise notification triggers immediate rotation per the incident policy above

Automation

At Qwestly's current scale (<10 employees), key rotation is performed manually by the CTO. As the team grows, we will evaluate secrets management tooling (e.g., Doppler, AWS Secrets Manager) to automate rotation.

Evidence Locations

Evidence Location Type
This policy document access-control/API-Key-Management.md Internal policy
Key inventory This document (table above) Internal record
May 21 compromise incident report incidents/2026-05-21-openai-key-compromise.md Incident record
Vercel env var configuration Vercel dashboard → Project Settings → Environment Variables Screenshot
Provider dashboards OpenAI API dashboard, VAPI dashboard, LangSmith dashboard Screenshot (token lists)

Testing & Validation

Test Frequency Owner Evidence
Key rotation executed per schedule Quarterly CTO Rotation record in change log
No production keys in code repos Per deploy (automated via CI) CTO GitHub secret scanning results
Vercel env vars match documented key inventory Quarterly CTO Screenshot comparison
Incident-triggered rotation drills Annually CTO Documentation of drill

Continuous Improvement

Review Cadence

  • Quarterly: CTO reviews key inventory, performs scheduled rotation, updates this document
  • Per incident: Policy and procedures reviewed after any key-related security event
  • Annually: Full policy review as part of SOC2 audit preparation

Planned Improvements

  • Evaluate secrets management service (Doppler, AWS Secrets Manager, 1Password CLIs) for automated rotation
  • Add automated expiry reminders (calendar or Vanta-based)
  • Implement CI checks that fail if production keys are detected in PRs