Rotate without downtime by running the old and new keys side by side. Create the new key, move callers over in stages, watch the old key's request logs, and expire the old key only after its traffic has been zero for a while. Never revoke first and fix breakage after.
Why rotation breaks things
An API key used by an integration is rarely used in only one place. The same key might sit in a production server, a staging copy, a cron job, a low-code automation and a teammate's notebook. Revoke it and every one of those fails at once, usually at night.
Some providers help with an overlap window. Stripe's documentation says that when you rotate a key in the dashboard, both the old and new keys work for up to 7 days, and that you can set the expiry. If you need longer, create a new key manually, migrate, then expire the old one. Check what your provider offers before you plan.
The rotation plan
| Step | Action | Check |
|---|---|---|
| 1 | Create the new key with the same, or narrower, permissions | Name and owner recorded |
| 2 | Store it in the secrets manager, not in code | Old key untouched |
| 3 | Move one small caller first, such as staging | No errors in its logs |
| 4 | Roll out to the rest in stages | Error rate steady |
| 5 | Watch the old key's request logs | Volume falling to zero |
| 6 | Expire the old key after a quiet period | Alerts quiet for a day or more |
| 7 | Remove the old key from every note and vault | Search finds none |
Finding the callers you forgot
Request logs are your inventory. When the old key still shows traffic after you believe everything moved, look at the source address, user agent and the operations being called. That usually points to the forgotten cron job or the automation someone built last year.
If the provider does not show per key logs, add an identifying header or use separate keys per caller from now on. Separate keys per integration make every future rotation smaller.
Compromise changes the plan
If the key leaked, skip the overlap. Revoke now, accept the outage, and rebuild. Overlap is for scheduled rotation, such as when a team member with access leaves, or when policy sets an interval. Stripe lists the same cases: a lost key, a compromised key, a person leaving or changing roles, and policy.
After rotation
- Write down the date and the next due date.
- Confirm the old key is truly expired by making a test call with it.
- If the old key was in version control history, treat history as exposed and rely on revocation, not deletion.
Quick check
How often should I rotate integration keys?
Follow your policy, and rotate on any staff change or suspected exposure. A fixed interval matters less than being able to rotate quickly and safely.
Can I just delete the key from the repository?
No. Anything that was committed should be treated as exposed. Revoke the key and issue a new one.
Safeguard's policies and compliance evidence automation can record rotation as a recurring control. Try the free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
