Plan API Key Rotation
Plan a provider API key change with dual-key overlap, caller inventory, health checks, rollback limits, and old-key rejection evidence.
A key rotation can fail in two directions: the old key remains accepted, or the new key breaks an overlooked caller. Plan both outcomes before touching a production provider. OWASP's secrets guidance treats rotation as part of a credential lifecycle, but each provider has its own issuance and revocation behavior. Verify those steps instead of assuming a generic "rotate" button exists.
List every caller of the current key: application instances, scheduled jobs, CI, local tools, and partner integrations. Use safe key IDs, not raw values. Identify the owner who can issue a replacement and the method that proves both keys' status.
Cutover timeline
| Stage | Checkpoint | Stop condition |
|---|---|---|
| Prepare | New key issued with minimum scope | Provider cannot create a safe overlap |
| Shadow | New key tested in owned environment | Expected request fails |
| Switch | Callers updated in a controlled order | Error rate or missing caller rises |
| Observe | New key works across key paths | Unknown old-key use persists |
| Revoke | Provider disables old key | Old key still accepted |
| Close | Receipts and owner signoff saved | Rollback would restore exposed key |
The rollback plan must not depend on re-enabling a compromised key. If the old key is suspected exposed, create a second clean replacement path or pause the affected feature. A provider may not support simultaneous keys; document the outage window and operator decision before the change.
Verification record
Use a harmless provider operation, if available, to test the new key's expected access and the old key's rejection after revocation. Keep the test inside an authorized account. Record time, provider response class, key ID, and service health without logging the key. Check background jobs after their normal schedule, not only the main web request.
Do not claim the rotation succeeded because a configuration file changed. Confirm all intended callers use the new key and no old-key use remains in provider logs where available. Revisit the plan when provider controls, credential scopes, or caller ownership change. Keep the plan separate from the execution receipt; the plan alone cannot prove that the old key stopped working.
Make offboarding verifiable
Use the offboarding checklist to identify owners, revoke grants and verify the result. Discuss a scoped review of your application's access controls.
Sources
- OWASP Secrets Management Cheat SheetAccessed
- OWASP REST Security Cheat SheetAccessed