Rotate API Keys Without Breaking Clients

Issue a new key, accept old and new during a migration window, track client usage, and revoke the old key only after every caller has moved.

intermediate~40 minsecurityapioperations

Objective

Replace a compromised or aging API key with zero unplanned client outages and a clear audit trail.

Environment

A key store that supports multiple active keys per client
Usage logs keyed by key id
A way to notify or contact API consumers
A rollback plan that can re-enable the old key

Steps

1. Inventory and classify

List every key, its owner, scopes, last-used time, and the clients that depend on it.

Expected state: No key is unknown, and high-impact keys have a named owner.

2. Issue the replacement

Create a new key with the same or narrower scopes and distribute it through the approved secret channel.

Expected state: The new key works and the old key still works during the overlap.

3. Migrate and observe

Track usage by key id, contact clients still on the old key, and set a revocation date.

Expected state: Old-key usage falls to zero or the remaining callers are explicitly accepted.

4. Revoke the old key

Disable the old key, confirm requests using it fail with 401, and monitor for a spike in errors.

Expected state: The old key is unusable and no critical client is broken.

5. Record the rotation

Store the reason, dates, owners, and any accepted exceptions in the audit log.

Expected state: The rotation is traceable and the next rotation date is set.

Decision points

Should the old key be revoked immediately?

Immediately when compromise is confirmed
After a migration window

Revoke immediately on confirmed compromise; otherwise use a bounded overlap and track usage.

Should the new key have the same scopes?

Same scopes for simplicity
Narrower scopes based on usage

Narrow the scopes when the usage data supports it; rotation is a good time to reduce privilege.

Expected outcome

The new key is in use, the old key is revoked, and no unplanned client outage occurs.

Verification

Confirm the old key returns 401, the new key succeeds, usage dashboards show the migration, and the key inventory reflects the new key and revocation date.

Cleanup

Delete temporary copies of the old key, archive usage evidence, and update the rotation schedule.

Two keys, one migration window

A rotation is a migration, not a switch. Issue the new key, accept both during a bounded window, and track which clients still use the old one. For a confirmed compromise, skip the overlap and revoke immediately; the incident response takes priority over client convenience.

key_old -> accepted until 2026-11-15
key_new -> active
usage by key_id -> dashboard

Make usage visible

Log key ids, not the secret values. A dashboard that shows requests per key id tells you when the migration is complete. Contact the owners of clients still using the old key and set a revocation date. Do not revoke based on a guess about who uses it.

Revoke and verify

Disable the old key and confirm a request with it returns 401. Watch error rates for the clients that missed the migration. Keep a short rollback window only if re-enabling the old key does not reintroduce the compromise. Record the rotation and the next due date.