API Key Rotation with Overlap

Overview

Rotation turns credential compromise from a permanent problem into a bounded one. The core trick is overlap: two keys valid at once so clients switch without a coordinated cutover.

Good developer experience decides whether rotation happens. Provide clear dashboards showing key age and last use, email owners before expiry, and offer an API for automated rotation. Document the rotation procedure in your integration guide and exercise the emergency revoke path in game days.

How it works

Key format:  sk_live_ab12cd34_<random 32B>    # prefix = lookup id
Store:       { prefix, sha256(secret), scopes, created, expires, lastUsed }

T0  client has key A
T1  client creates key B           (A and B both valid)
T2  client deploys B; A lastUsed stops advancing
T3  client or policy revokes A     (only B valid)
Verify: lookup by prefix, constant-time compare hash

Alerting on a revoked key still being presented can reveal a leak or a forgotten integration.

Pitfalls

• Storing keys in plaintext or reversible encryption. Hash them like passwords, though a fast hash suffices for high-entropy keys.
• Transmitting keys in URLs, which land in logs. Use headers.
• Non-expiring keys with no owner. Require an owner and expiry.
• Not scanning for leaks. Use a recognizable prefix so secret scanners and GitHub can flag exposures.
• Rotating on a calendar only; also have a tested emergency path.

Key takeaways

• Support at least two concurrent keys per client.
• Hash at rest, show once, scope and expire every key.
• Track last use to know when it is safe to retire the old key.
• Prefer short-lived tokens or workload identity where possible.