Guide · Security
How to Rotate API Keys Safely
Rotating API keys without downtime. Create new, update config, deploy, then revoke old. Here's the process.
Rotation without downtime is a Secrets Management pass condition—overlap old and new, then revoke. Primary control: Secrets Management
Never revoke first
Leaked or routine rotation both need the same order: new key live before old key dies. Revoking the only production key first is a self-inflicted outage. APRF Secrets Management treats overlap + verify + revoke as the pass path.
A team found a key in a public repo, revoked immediately, and took prod down until a scramble deploy. Creating the replacement first would have kept traffic green.
Cutover sequence
1. Create the new key (or dual-key in the provider)
2. Put it in Secrets Manager / deploy config—keep the old value readable during transition if your runtime can try both
3. Deploy and verify real traffic (health + a paid path)
4. Revoke the old key
5. Delete the old value from config and purge it from docs/CI
If apps fetch secrets on an interval, wait one refresh cycle before revoke.
Cadence
Rotate on leak immediately; otherwise on a schedule (often ~90 days) that matches your compliance story. Practice the runbook once so the first real leak is not the first rehearsal.
Next: Secrets Management
Open the related pillar specification for mandatory checks, artifacts, and pass conditions. Self-attest is optional.
Related
Frequently asked questions
- How do I rotate API keys without downtime?
- Create a new key first. Update your config with the new key. Deploy and verify. Then revoke the old key. Never revoke the old key before the new one is live.
- What happens if I revoke an API key before rotating?
- Your app will fail—all requests using that key will be rejected. Create the new key first, deploy, then revoke the old one.
- How often should I rotate API keys?
- Rotate immediately if leaked. For routine rotation, every 90 days is common. Some compliance frameworks require it.