API Key Rotation Best Practices
Plan zero-downtime API key rotation with overlapping credentials, scopes, audit logs, expiration, and leak response.
Rotation is a product workflow
API key rotation replaces an existing credential with a new one and retires the old secret. The cryptographic operation is simple; the difficult part is coordinating applications, jobs, environments, and team members without causing an outage.
A useful rotation workflow supports overlap. Customers create a new key, deploy it, verify traffic, and then revoke the old key. Forcing immediate replacement makes routine security work risky and encourages teams to postpone it.
Separate key identity from the secret
Store a stable key record with an identifier, owner, scopes, creation time, status, prefix, last-used time, and secret hash. Show the full secret only once. Logs should refer to the identifier or safe prefix, never the credential value.
This design lets you revoke or expire one secret without losing its audit history. It also supports several active keys for a workspace, which is necessary when production, staging, and individual services rotate on different schedules.
| Key state | Accept requests | Typical use |
|---|---|---|
| Active | Yes | Current production credential |
| Rotating | Yes, for a short overlap | Old key during deployment |
| Expired | No | Reached a documented end time |
| Revoked | No | Manual retirement or leak response |
Use a zero-downtime rotation sequence
Create the replacement with the minimum required scopes and a clear label. Update secret storage, deploy the new value, and confirm that recent traffic uses the replacement. Only then revoke the old key. Keep the overlap short enough to reduce exposure but long enough for deployment rollback.
- Inventory every service and environment that uses the old key.
- Create and securely distribute the replacement credential.
- Deploy, observe successful traffic, and test background jobs.
- Revoke the old key and monitor rejected requests for stragglers.
- Record who rotated the key and why.
Choose rotation triggers based on risk
Calendar rotation can reduce long-lived exposure, but it is not the only trigger. Rotate immediately after suspected disclosure, employee or vendor offboarding, an overly broad scope, an environment move, or a security incident. High-privilege keys deserve shorter lifetimes and stricter controls.
Avoid rotation schedules that teams cannot operate reliably. A well-automated 90-day process is safer than a 30-day policy that is repeatedly bypassed. Short-lived tokens or workload identity can remove manual key rotation from some server-to-server use cases.
Make leak response fast and observable
Emergency revocation should be prominent, immediate, and confirmed. Show recent routes, IP addresses, usage, and cost linked to the affected key so the owner can estimate impact. Notify account owners and preserve evidence needed for billing or security review.
After revocation, distinguish expected failures from continuing malicious attempts. A spike of rejected calls may reveal an undeployed service, while traffic from a new location may support the leak diagnosis. Document how disputed usage is reviewed in the API key policy.