Security and operations
OpenAI-Compatible API Key Rotation Policy for SaaS Teams
A practical policy for rotating customer API keys, provider keys, and gateway secrets in OpenAI-compatible SaaS AI products without breaking billing or usage attribution.
Why key rotation is harder for AI gateways
In a normal API product, key rotation is mostly a security task. In an AI API gateway, it also touches model routing, customer-level quotas, prepaid balances, provider pools, audit trails, and usage-based billing. A rushed rotation can break production workloads or detach usage from the customer who should pay for it.
The safer approach is to treat every key as a versioned credential with ownership, billing attribution, allowed models, spending limits, provider scope, and a clear retirement state.
Separate the three key layers
| Layer | Who owns it | Rotation trigger | What must stay stable |
|---|---|---|---|
| Customer API key | Your tenant or end user | Leak, employee offboarding, plan change, scheduled hygiene | Tenant id, quota policy, prepaid balance, usage attribution |
| Gateway signing secret | Your platform team | Deployment boundary, incident response, environment migration | Request audit trail, webhook verification, admin access controls |
| Provider API key | Your AI ops or finance team | Provider leak, account pool migration, vendor pricing change | Model aliases, fallback rules, customer-visible availability, invoice reconciliation |
A practical rotation policy
- Create before revoke. Let customers or admins create a replacement key, copy the existing model permissions, and attach it to the same tenant billing profile.
- Run dual keys during the migration window. Keep old and new keys active long enough for background jobs, IDEs, workers, and customer integrations to update safely.
- Mark old keys as deprecated before disabling them. Show last-used time, request count, model usage, and estimated cost so teams can find forgotten clients.
- Preserve ledger continuity. Usage from both old and new keys should roll up to the same tenant, plan, prepaid balance, and invoice line unless ownership changed intentionally.
- Revoke with a reason code. Store whether the key was rotated for hygiene, suspected leak, offboarding, abuse, payment risk, or provider migration.
Rotation states to implement
| State | Behavior | Customer-facing message |
|---|---|---|
| Active | Accept traffic and bill normally. | None. |
| Deprecated | Accept traffic, emit warning headers/events, show replacement guidance. | “This key is scheduled for rotation.” |
| Read-only / limited | Allow low-risk models or small quota while blocking expensive routes. | “This key is limited during security review.” |
| Revoked | Reject all requests and keep historical usage immutable. | “This key has been revoked. Create a new key or contact an admin.” |
Provider key rotation checklist
- Move a small traffic slice to the new provider key before moving the full route.
- Confirm model ids, context limits, streaming behavior, and price tables match your billing assumptions.
- Watch fallback ratio and cost anomaly alerts during the switch.
- Keep provider account ids in the usage ledger so invoice reconciliation still works after rotation.
- Do not delete the old provider key record until all historical invoice windows are reconciled.
Recommended audit fields
For every key version, store: tenant id, key id prefix, creator admin id, created time, last-used time, allowed model groups, quota policy id, billing profile id, prepaid balance account, provider pool, rotation reason, deprecation deadline, revoke time, and revoking actor.
Never log full API keys in request traces, analytics, tickets, or billing exports. Store only a hash and a short display prefix.
Key rotation should also update logging rules: follow an AI API request logging redaction checklist so deprecated keys, provider traces, and incident captures do not leak sensitive data.
Related: keep key rotation, role grants, and emergency revocations traceable with AI API admin audit log requirements.