What This Is
API keys and secrets are the keys to your kingdom. If they're stolen, anyone can read your data, delete your resources, or impersonate your services. Rotation isn't just a best practice — it's the only way to limit the damage of a breach. This checklist gives you a repeatable process for keeping your secrets fresh and your systems secure.
Why You Need This
- Limit breach impact: The sooner you rotate, the fewer records an attacker can access.
- Compliance requirement: Many regulations (PCI-DSS, HIPAA, SOC 2) mandate regular rotation.
- Automated testing: Rotation is the perfect time to verify your secrets flow works end-to-end.
- Psychological security: Regular rotation makes security part of the daily rhythm, not an afterthought.
Pre-Rotation Preparation (15 Minutes)
Don't rotate in the dark. Gather everything you need first.
Pre-Rotation Checklist
- [ ] Identify all keys to rotate: APIs, databases, cloud services, third-party integrations.
- [ ] Map key to service: Which app/service depends on each key? Document this.
- [ ] Schedule downtime: Can you rotate during off-hours? Or do you need a brief outage?
- [ ] Notify stakeholders: Operations, DevOps, engineering, any external partners.
- [ ] Backup key mappings: If you can't back up keys, you'll reconfigure by hand — slow and error-prone.
- [ ] Create new keys first: Rotate in order: rotating order matters to avoid breaking dependencies.
- [ ] Test write access: Verify new keys work before you revoke old ones.
During Rotation (30-60 Minutes)
Follow this order to minimize disruption. Rotate in the right direction: add new before removing old.
Rotation Sequence
- Add new keys to config: Deploy updated configs with fresh keys to all environments.
- Update service restarts: Restart services to pick up new configs. Do this in order of dependency.
- Verify in staging first: Test that new keys work correctly before touching production.
- Add cooldown period: Wait 5-10 minutes after each service restart to ensure stability.
- Roll out to production: Gradually rotate each key, one at a time.
- Verify endpoints: Test critical endpoints manually or via automated smoke tests.
Post-Rotation Verification (10 Minutes)
Don't assume it worked. Verify with data, not hope.
Post-Rotation Checklist
- [ ] Check logs: No failed auth attempts? No 403 errors?
- [ ] Functional test: Use the key to perform a real operation in staging.
- [ ] Monitoring alerts: Did security alerts fire incorrectly? Adjust thresholds.
- [ ] Data verification: Are you seeing the same data you saw before rotation?
- [ ] Key deletion: Once verified, delete old keys from your secret store.
- [ ] Archive old key: Keep a backup for audit purposes. Delete only after a retention period.
- [ ] Document the rotation: Which key, when, why, any issues. This is your audit trail.
Rotation Schedule Guidelines
How often should you rotate? The rule of thumb: rotate before credentials are likely to be compromised.
Schedule by Risk Level
- High risk (internal, admin): Every 90 days minimum.
- Medium risk (user-facing API): Every 180 days.
- Low risk (read-only integrations): Annually, but always rotate on breach.
- Temporary keys: Always rotate immediately after use.
Worked Example
A fintech startup lost $120,000 when an old API key was stolen and used to withdraw funds. The key had been created 2 years earlier and never rotated.
They implemented this rotation schedule: internal admin keys every 90 days, user-facing API keys every 6 months. They automated the rotation process using a GitOps workflow: a PR with new keys → automated testing → merge → deployment. Failed tests → no rotation. Success → rotation complete.
Result: After one year, they had 12 rotations with zero incidents. Their security team confidently reported: "We can't fix stolen credentials, but we control how long they're valid."