API Key Management

Overview

API keys are the primary authentication method for AI Gateway. Proper key management is critical for security.

Key Types

Gateway API Keys

• Format: gw_sk_[random-string]
• Purpose: Authenticate requests to AI Gateway
• Created in: AI Gateway Settings

Provider API Keys

• Format: Varies by provider (sk-... for OpenAI, sk-ant-... for Anthropic)
• Purpose: Authenticate with upstream providers
• Stored in: AI Gateway Settings (encrypted)

Creating Gateway Keys

1. Navigate to AI Gateway Settings
2. Under "Gateway API Keys", click Create API Key
3. Enter a descriptive name:
   • production-api
   • development
   • ci-testing
   • mobile-app
4. Click Create
5. Immediately copy the key - it won't be shown again

Key Storage

Environment Variables (Recommended)

# .env (local development)
GATEWAY_API_KEY=gw_sk_your_key_here
 
# Never commit .env files!

Secret Managers

For production, use a secret manager:

AWS Secrets Manager:

aws secretsmanager create-secret \
  --name gateway-api-key \
  --secret-string "gw_sk_your_key_here"

HashiCorp Vault:

vault kv put secret/gateway api_key="gw_sk_your_key_here"

Vercel:

vercel env add GATEWAY_API_KEY production

Kubernetes Secrets

apiVersion: v1
kind: Secret
metadata:
  name: gateway-secrets
type: Opaque
stringData:
  GATEWAY_API_KEY: gw_sk_your_key_here

Key Rotation

Rotate keys regularly (recommended every 90 days):

Rotation Process

1. Create new key in the dashboard
2. Update applications to use new key
3. Deploy the changes
4. Monitor for any errors using old key
5. Revoke old key after confirming all traffic uses new key

Zero-Downtime Rotation

// Support multiple keys during transition
const apiKeys = [
  process.env.GATEWAY_API_KEY_NEW,  // New key
  process.env.GATEWAY_API_KEY_OLD,  // Old key (fallback)
].filter(Boolean);
 
let currentKeyIndex = 0;
 
async function callWithKeyRotation(fn) {
  for (let i = 0; i < apiKeys.length; i++) {
    try {
      return await fn(apiKeys[currentKeyIndex]);
    } catch (error) {
      if (error.status === 401) {
        currentKeyIndex = (currentKeyIndex + 1) % apiKeys.length;
        continue;
      }
      throw error;
    }
  }
  throw new Error('All keys failed');
}

Key Scopes (Coming Soon)

Future release will support scoped keys:

Security Best Practices

Do

• Use different keys for different environments
• Store keys in environment variables or secret managers
• Rotate keys regularly (every 90 days)
• Monitor key usage in the dashboard
• Revoke keys immediately when compromised
• Use descriptive names for keys

Don't

• Commit keys to version control
• Share keys between applications
• Log keys in application output
• Expose keys in client-side code
• Use production keys in development
• Keep unused keys active

Monitoring Key Usage

Dashboard Metrics

View per-key metrics:

1. Go to AI Gateway > Settings
2. Click on a key to see:
   • Request count
   • Last used timestamp
   • Error rate

Audit Logs

Track key usage:

1. Go to Settings > Audit Logs
2. Filter by "API Key" events
3. View key creation, usage, and revocation

Responding to Compromised Keys

If a key is exposed:

Immediate Actions

1. Revoke the key immediately in Settings
2. Create a new key
3. Update applications with new key
4. Deploy changes

Investigation

1. Check Audit Logs for unauthorized usage
2. Review Request Logs for suspicious patterns
3. Assess Cost Impact of any misuse

Prevention

1. Review how the key was exposed
2. Improve secret management practices
3. Consider using IP allowlists

Key Naming Conventions

Use consistent naming for easy management:

{environment}-{application}-{purpose}

Examples:

• production-api-primary
• production-api-backup
• staging-api-testing
• development-local
• ci-github-actions

Next Steps

• IP Allowlist - Restrict by IP
• Authentication - API auth details
• Rate Limiting - Usage limits