Rotation is two things: a fixed sequence of steps, and a calendar reminder that tells you when to run them. The steps haven't changed in a decade. The cadence is up to you. Here is the checklist most teams should use, and the parts most teams skip.
Most rotations follow the same six steps. The order matters. Skipping any of them is what causes the outages and the audit findings.
Nearly every rotation outage comes from the same mistake: revoking the old key before every consumer has migrated to the new one. The fix is the transition period, the window where both keys are valid at the same time. Most providers support this natively.
How long should the window be? It depends on what consumes the key:
If you skip the transition period and revoke immediately, you'll get paged. If you stretch it forever and never revoke, you have not rotated. The old key is still valid, the rotation logs say "done," and the audit finding comes anyway.
Each of these has caused a real outage on a real team.
You deploy the new key, refresh once, then revoke. Five minutes later your cron job that runs every six hours wakes up and fails because nobody told it about the rotation.
Production gets the new key. Staging, the CI pipeline, the scheduled report runner, and the contractor's local .env file do not. The old key is in use across half your stack.
The transition period becomes permanent. A year later you have eight valid keys for one service, each with full access, all leaked somewhere different.
You rotated, but nobody wrote down when or by whom. The SOC 2 auditor asks for the rotation log and you have to reconstruct it from Slack messages.
The key was committed in 2022. Now you're rotating the live env var, but the value also lives in three git branches and a Dockerfile. Pull from secrets, not source.
The most common failure mode. There was no rotation policy, no calendar entry, no follow-up. Someone noticed last quarter that the key was three years old.
SOC 2, ISO 27001, PCI DSS, and most compliance frameworks expect a documented record of rotations. The format doesn't matter much. The existence of the record does.
A shared spreadsheet works. A Notion table works. A row in a database works. What does not work is "we definitely did this, we just don't remember exactly when."
The full process takes about 30 minutes if you've done it before. The longer transition windows happen in the background. The hard part is not the work, it's the 90-day gap of forgetting in between.
See the main API key rotation reminder page or read how often to rotate for the cadence side of the question.
Set a reminder for your next rotation date. Get an email with enough time to actually run the checklist.
Done in seconds. No sign-up required.
Use a transition period. Most providers let two valid keys exist at the same time. Provision the new key, deploy it to production, watch logs until traffic on the old key drops to zero, then revoke. The transition period is the gap that prevents downtime: usually a few hours to a day.
The window where both the old and new key are valid simultaneously. It lets cached configurations, queued jobs, scheduled tasks, and slow-deploying environments finish using the old key before you revoke it. Without a transition period, you cause an outage every time you rotate.
Long enough that every legitimate consumer of the old key has migrated. For stateless production services, a few hours is enough. For systems with cached config, batch jobs, or weekly cron schedules, extend to 24 to 72 hours. If you have a job that runs monthly, hold the old key for at least a month.
No. Once you have verified the new key works and the old key has zero traffic, revoke it and delete it everywhere. Keeping an old key around in case of rollback defeats the purpose of rotation. If the rotation fails, generate yet another new key.
Most providers offer per-key usage logs. Check the dashboard for the last 24 hours of activity by key ID before revoking. If the old key shows nonzero traffic after the deploy, find the service still using it before you revoke. A surprise outage is the rotation failing loudly.
The key ID rotated, the date, the operator, and the next rotation due date. Most teams keep this in a simple spreadsheet or in their incident tracker. Auditors want to see a paper trail proving rotations happen on cadence, and so does future-you when you need to know whether a key was rotated before a known leak window.
Free. No account. Get notified before the date so you actually run the checklist instead of pushing it again.
Create API Key Rotation ReminderLast modified: