How to rotate an API key without downtime

Rotating a key means replacing it with a new one and switching the old one off. Done in the right order, your app never notices. Done in the wrong order, production breaks until you find every place the old key lived.

This guide works for most providers: Stripe, OpenAI, Anthropic, Resend, GitHub tokens, cloud access keys and the rest. The rule is the same everywhere: the old key stays active until the new one is proven to work.

Before you start

Know which account owns the key. If you run several products, you may have two Stripe accounts or three Vercel teams. Rotating in the wrong one creates a key nothing uses.
List every place the key is used. Production and preview environment variables, CI secrets, background workers, cron jobs, local .env files, and anything a teammate or AI agent set up.
Check the key's permissions. The replacement needs the same access. A rotation is also a good moment to narrow it, for example a restricted key instead of a full secret key, if the provider supports that.

The steps

Generate a new key. Sign in to the account that owns the key and create the replacement in the provider dashboard, with the same permissions as the old one. Keep the old one active for now.
Save the new value somewhere safe. Many providers only show a secret once. Store it in your password manager or vault before you close the page, not in a chat message or a scratch file.
Update every deploy target. Replace the value in each environment variable that holds it: Vercel, Netlify, GitHub Actions secrets, your server's config. Then update anywhere else you use it.
Redeploy. Most hosts only read environment variables when a build or deployment starts. A changed variable does nothing until you redeploy production (and re-run any workflow that reads the secret).
Verify it works. Deploy or run a request, and check that nothing is failing. Watch your logs and the provider's dashboard for errors in every environment you changed.
Revoke the old key. Only after verifying the new one. This is what makes the rotation count: if the old key ever leaked, it stops working now.
Record the rotation. Note the date and set a reminder for the next one, or for the new key's expiry date if it has one.

Why the order matters

Each step protects the next one. If you revoke first, every request fails until the new key is deployed everywhere. If you skip the redeploy, the new value sits in your settings while the running app keeps using the old one, and revoking breaks production anyway. If you skip verification, you find the place you forgot when customers do.

Some providers let old and new keys overlap for a while after you rotate from their dashboard. That window is a safety net, not a plan: finish the switch and revoke as soon as the new key is confirmed. Provider details are on each provider page, for example Stripe, GitHub and OpenAI.

Places keys hide

Preview and staging environments, not just production.
A second hosting project or a forgotten old deployment that still runs.
CI secrets used for migrations, seed scripts or end-to-end tests.
Scheduled jobs, queues and webhooks that run somewhere other than your main app.
Local .env files on your laptop and your teammates' laptops.
Keys an AI coding agent created or pasted into a config for you.

Database passwords and domains

Database passwords work differently: many providers stop accepting the old password the moment you reset it. To switch over without downtime, create a second database user with the same permissions, move every connection string to it, verify the app connects, then drop the old user. If you reset the password in place, have every place that uses it ready to update first.

Domains don't rotate, they renew. The same habit applies: renew at the registrar before the expiry date, turn on auto-renew, check that a valid card is on file, and record the new renewal date.

How often to rotate

Rotate right away when someone with access leaves, when a key was shared somewhere it shouldn't be, or when a provider retires a key format. Otherwise, pick a schedule you will actually keep, such as every 90 days for production keys, and set a reminder. Tokens with a fixed lifetime, like many personal access tokens, force the schedule for you: the only question is whether you find out before your deploys fail.

Think the key leaked? That's a different order of work: speed matters more than a clean switch. Follow the leaked API key playbook instead.

Do this in StackHangar

StackHangar runs this same playbook against your own stack. Because your vault already knows which account owns the key, where it's deployed and when it's due, the steps come pre-filled for that key. Rotation reminders tell you when it's time.

On Solo, the push and redeploy steps run from your browser to Vercel, GitHub or Netlify. The new value goes straight to the provider and never reaches our servers.
Your AI agent can propose the rotation. You review it and approve with a passkey, and the agent never sees the key.
The reminder resets when you finish. Free covers 2 projects.

Start free Leaked key playbook