Key Rotation Runbook

Consistent key rotation protects AISentinel tenants from credential leakage and satisfies compliance controls. This runbook covers automated schedules for API keys and BYOK master keys, re-encryption workflows, and zero-downtime strategies.

Rotation Strategy Overview

Automating API Key Rotation

1. Create a New Key using the Admin API (POST /v1/api-keys).
2. Deploy the New Key into your secret manager. Mark old key as pending.
3. Notify Applications:
   • Python SDK: call client.auth.reload() or rely on RotatingApiKeyProvider (see Authentication).
   • JavaScript SDK: update environment variables and trigger blue/green deploy.
4. Validate Traffic: Monitor the Usage Dashboard to confirm traffic shifts to the new key.
5. Revoke Old Key: DELETE /v1/api-keys/{id} once traffic drops to zero.

Sample Automation Script (Python)

from aisentinel import Client

admin = Client(api_key="${AISENTINEL_ADMIN_KEY}", tenant_id="acme-prod")

new_key = admin.api_keys.create(
    name="prod-langchain-2024-05",
    scopes=["policies:read", "policies:write"],
    expires_in_days=30,
)
# Store new_key.secret securely
admin.api_keys.schedule_revocation(key_id="old-key-id", revoke_at="2024-05-30T00:00:00Z")

The schedule API ensures revocation occurs after dependent deployments complete.

Rotating BYOK Master Keys

Step 1: Enable Provider Rotation

• AWS KMS: aws kms enable-key-rotation --key-id <key-arn>
• Azure Key Vault: az keyvault key rotation-policy update --vault-name acme-prod-kv --name AISentinelMaster --expiry-time 90d
• GCP Cloud KMS: gcloud kms keys update aisentinel-master --keyring acme-governance --rotation-period 7776000s

Step 2: Inform AISentinel

When the provider rotates the key, notify AISentinel to use the latest version:

curl -X POST "https://api.aisentinel.ai/v1/encryption/byok/rotate" \
  -H "Authorization: Bearer $AISENTINEL_ADMIN_KEY" \
  -H "X-AISentinel-Tenant: $AISENTINEL_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "kmsKeyArn": "arn:aws:kms:us-east-1:123456789012:key/abcd-1234",
    "rotateMode": "lazy"
  }'

• rotateMode: "lazy" decrypts objects on access and re-encrypts with the new key.
• Use rotateMode: "eager" for immediate re-encryption of all stored data. AISentinel queues background jobs while keeping APIs available.

Step 3: Monitor Re-Encryption

• Check rotation job status via GET /v1/encryption/byok/status.
• Review audit events encryption.key.rotate_started and encryption.key.rotate_completed in Auditing & Compliance.
• Configure alerts for failures or retries.

Zero-Downtime Deployment Patterns

• Blue/Green Releases: Deploy new credentials to idle infrastructure first, run smoke tests, then switch traffic.
• Feature Flags: Use environment flags to swap API keys at runtime for serverless platforms.
• Retry Semantics: Respect Retry-After headers during rotation windows to avoid cascading failures.
• Connection Pools: For proxies, ensure connection pools reload headers when secrets rotate.

Compliance and Evidence

• Log each rotation in your ticketing system with links to AISentinel audit IDs.
• Export rotation reports monthly for SOC 2 CC6.1 and HIPAA §164.308(a)(8).
• Pair rotation evidence with Cryptographic Proofs when decommissioning datasets.

Troubleshooting

• 401 invalid_api_key: Confirm new key is deployed and old key is revoked only after traffic cutover.
• 403 kms_access_denied: Update KMS key policies to allow the new key version.
• 429 rate_limit: Stagger re-encryption jobs or contact support to raise limits for eager rotations.

Implementing disciplined rotation keeps your governance boundary resilient and audit-ready.