Key Rotation

Regular key rotation limits exposure if a key is compromised. GateFlow supports automated and manual key rotation.

Why Rotate Keys?

• Limit Blast Radius: Compromised keys only work for a limited time
• Compliance: Many security standards require periodic rotation
• Offboarding: Rotate when team members leave
• Hygiene: Good security practice

Manual Rotation

Step 1: Create New Key

curl -X POST https://api.gateflow.ai/v1/management/api-keys \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Production (v2)",
    "type": "production",
    "permissions": { ... }
  }'

Step 2: Update Your Application

Deploy your application with the new key:

# Update environment variable
export GATEFLOW_API_KEY="gw_prod_new_key_here"

# Or update secrets manager
aws secretsmanager update-secret \
  --secret-id gateflow-api-key \
  --secret-string "gw_prod_new_key_here"

Step 3: Verify New Key Works

Make a test request with the new key:

curl https://api.gateflow.ai/v1/models \
  -H "Authorization: Bearer gw_prod_new_key_here"

Step 4: Revoke Old Key

Once the new key is deployed and verified:

curl -X DELETE https://api.gateflow.ai/v1/management/api-keys/old_key_id \
  -H "Authorization: Bearer gw_prod_admin_key"

Automated Rotation

Enable Auto-Rotation

Configure automatic rotation in the dashboard:

1. Go to Settings → API Keys
2. Select a key
3. Click Configure Rotation
4. Set rotation interval (30, 60, or 90 days)
5. Configure notification webhook

Rotation Webhook

GateFlow sends a webhook before rotating:

{
  "event": "api_key.rotation_pending",
  "key_id": "key_abc123",
  "current_key_last_4": "...ef56",
  "new_key": "gw_prod_new_key_here",
  "rotation_at": "2024-02-15T00:00:00Z",
  "grace_period_ends": "2024-02-22T00:00:00Z"
}

Timeline:

1. T-7 days: Webhook sent with new key
2. T-0: New key becomes primary
3. T+7 days: Old key revoked (grace period ends)

Webhook Handler Example

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/gateflow', methods=['POST'])
def handle_rotation():
    data = request.json

    if data['event'] == 'api_key.rotation_pending':
        new_key = data['new_key']

        # Update your secrets manager
        update_secret('gateflow-api-key', new_key)

        # Trigger deployment
        trigger_deployment()

        return {'status': 'ok'}

    return {'status': 'ignored'}

Zero-Downtime Rotation

For production systems, follow this pattern:

1. Parallel Key Support

Configure your application to try multiple keys:

import os

GATEFLOW_KEYS = [
    os.environ.get('GATEFLOW_API_KEY_PRIMARY'),
    os.environ.get('GATEFLOW_API_KEY_SECONDARY'),
]

def get_client():
    for key in GATEFLOW_KEYS:
        if key:
            return OpenAI(
                base_url="https://api.gateflow.ai/v1",
                api_key=key
            )
    raise Exception("No valid API key configured")

2. Rolling Update

1. Create new key
2. Set as GATEFLOW_API_KEY_SECONDARY
3. Deploy (both keys now work)
4. Promote secondary to primary
5. Deploy again
6. Revoke old key

3. Kubernetes Secret Rotation

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: gateflow-secret
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault
    kind: SecretStore
  target:
    name: gateflow-api-key
  data:
    - secretKey: api-key
      remoteRef:
        key: gateflow/api-key
        property: current

Rotation Audit Log

All rotations are logged:

curl https://api.gateflow.ai/v1/management/audit-log \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -G -d "event_type=api_key.rotated"

Response:

{
  "events": [
    {
      "id": "evt_123",
      "type": "api_key.rotated",
      "key_id": "key_abc123",
      "actor": "system",
      "timestamp": "2024-01-15T00:00:00Z",
      "details": {
        "rotation_type": "automatic",
        "old_key_last_4": "...ab12",
        "new_key_last_4": "...ef56"
      }
    }
  ]
}

Best Practices

Rotation Schedule

Environment	Rotation Frequency
Development	90 days
Staging	60 days
Production	30 days

Emergency Rotation

If you suspect a key is compromised:

1. Immediately create a new key
2. Deploy the new key
3. Immediately revoke the old key
4. Review audit logs for unauthorized usage
5. Report to security team

# Emergency revocation
curl -X DELETE https://api.gateflow.ai/v1/management/api-keys/compromised_key_id \
  -H "Authorization: Bearer gw_prod_admin_key"

Next Steps

• Organizations & RBAC - Team access control
• API Keys Reference - Full API documentation