Skip to content
apikit

Rotating API keys safely

A practical rotation playbook: dual-write, blue-green keys, secret managers, and how to verify the rotation worked.

Published 1/20/2026

Rotating an API key without dropping traffic is a five-minute job done correctly and a 4am pager going off done incorrectly. Here's the pattern that holds.

Blue/green secrets

The mental model is the same as a blue/green deployment, but for credentials. At any moment, two keys exist for the same scope: the one currently in use (blue), and a new one ready to take over (green). Code reads from a single env var; that var gets switched from blue to green in a single deploy.

The five steps

  1. Provision the new key. Same scope, same project, same workspace. Drop it into your secret manager under a versioned key (OPENAI_API_KEY_v2) — not by overwriting the old one.
  2. Deploy code that reads either. Many teams skip this. Don't. The fallback is what makes the rotation safe: OPENAI_API_KEY = OPENAI_API_KEY_v2 ?? OPENAI_API_KEY_v1. Now you can swap secret manager values without a code deploy.
  3. Roll the secret manager value. Point OPENAI_API_KEY at v2.
  4. Verify zero traffic on the old key. Open the provider console; watch the per-key usage chart for a full hour. If you see any traffic on v1 after the switch, something is using a stale env that hasn't restarted.
  5. Revoke v1. Only after the verification window passes. Don't be tempted to do it earlier "to clean up."

Cron the rotation

Manual rotations don't happen. They get postponed; the postponement is forgotten; the key sits for a year. Schedule it: a quarterly Github Action that opens a PR with a TODO; or, better, a fully automated pipeline that uses the provider's management API to mint a new key, write it to your secret manager, and trigger redeploy.

Per-environment, not per-build

Don't rotate prod and staging at the same time. Stagger by a week. If the rotation breaks something, you want staging to be the canary.

Emergency rotation

If a key is leaked, skip the gradual dance: revoke immediately and accept the brief outage. The data exfiltration risk vastly outweighs the inconvenience. After the emergency, audit how the key escaped and tighten the gap (pre-commit hooks, secret scanning, log redaction).

What about user keys?

If you let end-users store their own LLM keys with your app — common pattern for "bring your own key" SaaS — be very careful with rotation. Your job is to securely store them; the user's job is to rotate them. Push reminders, but don't try to rotate on their behalf.

What to do next

Make sure the key you're testing here is the one in your secrets manager. Use the APIKit tester to confirm v2 is alive before you flip the switch on v1.

Related guides