API key rotation — how to rotate without downtime
Rotating an API key without taking your app down requires a specific dual-read single-write sequence. Here is the exact pattern.
The hard part of key rotation is not issuing a new key — it is making sure every system that uses it switches atomically. This guide covers the dual-read single-write pattern.
What it is
API key rotation replaces a current key with a new one without a window where either no key or the wrong key is in use.
Vulnerable example
// Bad: naive rotation
// 1. Generate new key
// 2. Update production env var
// 3. Delete old key
// -> Any request in flight with the old key fails during step 2.
// -> Any cached background worker using the old key fails.Fixed example
// Good: dual-read single-write
// 1. Generate new key (old still active)
// 2. Deploy: server accepts EITHER key for incoming requests
// 3. Update ALL clients / workers / cron to use the new key
// 4. Monitor: 0 requests using old key for >= 24 hours
// 5. Delete old key
// For outbound keys (Stripe/OpenAI/etc.):
// 1. Generate new key
// 2. Deploy: outbound uses new key
// 3. Delete old key (provider-side) once fleet fully migratedHow Securie catches it
Securie's secret lifecycle manager schedules rotation reminders, tracks key-usage telemetry, and proposes rotation PRs automatically for keys older than the configured threshold.
Checklist
- Rotation documented per key class (session-signing, provider API, OAuth, webhook)
- Dual-read period of at least 24 hours for inbound keys
- Telemetry: count of requests by key version
- Automation covers the common cases (Stripe, OpenAI, Anthropic, Supabase)
- Rotation on every team-member departure for keys the member had access to
FAQ
How often should I rotate proactively?
Session-signing secrets: quarterly at minimum. Provider API keys: quarterly if cheap, annually otherwise. OAuth client secrets: annually or on any credential leak.