Lorixen.
EN

Rotating API keys and secrets without downtime

Short answer: API keys and other secrets, such as payment keys, email service keys, database passwords and webhook signing secrets, should be replaced on a schedule and immediately when someone leaves or a key may have leaked. The trick is doing it without downtime: create the new secret, let old and new work side by side for a short overlap, roll the new one out, confirm the old one is no longer used, then revoke it. Keep an inventory so you know which secrets exist and where each one lives, and automate rotation where your providers support it.

Why rotate at all

A secret that never changes is valid forever for anyone who ever saw it: a former developer, an agency you stopped working with, a laptop that was lost, a log file that captured it, a repository it was briefly committed to. OWASP's Secrets Management Cheat Sheet recommends rotating secrets regularly so that any stolen credentials only work for a short time, and notes that regular rotation also discourages bad habits such as reusing credentials.

The same cheat sheet makes a point small teams often miss: restarting an application does not revoke stolen credentials; they stay usable until the service behind them expires or revokes them.

When to rotate

Stripe's documentation on API keys gives a practical list of situations, which applies well beyond payments:

  • You lost a secret key and cannot recover it.
  • A key is compromised and you need to block potentially malicious requests.
  • A team member with access leaves or changes roles.
  • Your policy requires rotation at set intervals.

Add to that: after an agency or freelancer engagement ends, after a key was pasted into chat or email, and after any security incident on a machine that held keys.

Start with an inventory

You cannot rotate what you do not know about. List every secret your website and apps use:

  • What it is: payment provider, email API, SMS, maps, database, cloud storage, webhook signing secret.
  • Where it is stored: hosting environment variables, a secrets manager, a CI system, a mobile app's back end.
  • Which services use it.
  • Who can see it, and when it was last rotated.

This list is also what you need on the day a key leaks, when every minute counts.

Rotating without downtime

The key is an overlap period when both old and new secrets work. Stripe describes this well. When you rotate a key in its dashboard, both the old and new keys work for up to seven days, so you can migrate gradually; if you need longer, create a new key manually, migrate, then expire the old one. Its documentation also recommends rolling the new key out to a subset of servers first while watching logs for errors, and checking the old key's request logs so you expire it only after its usage has been at zero for a few hours or days.

A general sequence for any provider:

  1. Create a new secret alongside the old one.
  2. Update your secret storage and deploy the new value, service by service.
  3. Verify everything works with the new value.
  4. Monitor the old secret's usage, through provider logs if available.
  5. Revoke the old secret.
  6. Record the date and who did it.

If a provider only allows one key at a time, schedule the change during a quiet period and update all services together, with someone ready to roll back.

In an emergency

If a key has leaked, speed matters more than a graceful overlap. Revoke or rotate immediately, accept a brief interruption if necessary, and then check the provider's logs for activity you do not recognise, such as charges, sent emails or new resources. Afterwards, find out how it leaked and close that gap.

Make rotation easier over time

  • Store secrets in one place, such as a secrets manager or your hosting platform's encrypted environment settings, not scattered across config files.
  • Load secrets at start-up or on demand so changing one does not need a code change.
  • Use restricted keys with only the permissions each service needs, where providers offer them, so a leak exposes less.
  • Prefer short-lived credentials, such as cloud roles, over long-lived keys. OWASP's cheat sheet favours dynamically created secrets with short lease durations where possible, and recommends automating rotation of static secrets because manual rotation is error-prone.
  • Keep secrets out of code and mobile apps. Anything shipped inside an app should be treated as public.

Webhook and signing secrets

Webhook signing secrets need extra care, because the sender and your app must agree. Many providers let you have two active signing secrets temporarily, or show both during a rotation, so you can update your verification code to accept either before switching. Check your provider's process before you start.

A worked example

Picture a hypothetical Vancouver yoga-studio group whose booking site had used the same payment, email and SMS keys for five years, through two agencies. Nobody was sure who still had copies.

A developer built an inventory of eleven secrets, moved them into the hosting platform's encrypted settings, and rotated each one: the payment key using the provider's overlap period while watching request logs until the old key showed no use, the email key during a quiet evening because only one key could be active, and the webhook secret using the provider's dual-secret option. Restricted keys replaced full-access ones where possible. Rotation is now on the calendar every six months and after any staff or agency change.

FAQ

How often should we rotate?

It depends on the secret's power and your risk. Many teams choose every few months, plus immediately after any access change.

Does rotation break mobile apps?

Not if secrets live on your server, as they should. Apps should call your back end, not providers directly with secret keys.

Who should be allowed to see live keys?

As few people as possible, ideally nobody routinely; deployments read them directly from secure storage.

If your site still runs on keys from years ago and you're not sure who has them, tell us which services it connects to.

Sources

WhatsAppBook a call