Skip to content
Free$1 of credit for every new organization
All articles

Security

Rotating API keys without downtime

A step-by-step routine for replacing an API key, whether on a schedule or because one leaked, without dropping a single request.

· 3 min read · Usefully team


API keys end up in more places than anyone plans: environment files, CI secrets, a teammate's shell history, a screenshot in a bug report. Rotating them regularly limits how long a leaked key stays useful, and having practised the routine means a real leak is a five-minute job instead of a scramble.

How Usefully keys work

  • A key is shown once, when it's created. We store only a salted hash, so nobody (including us) can read it back later.
  • Keys belong to an organization, and every key draws on the organization's credit balance.
  • Each key can have its own limits: requests per minute, tokens per minute and a daily spend limit.
  • Revoking a key takes effect almost immediately.

Because an organization can have many keys at once, rotation is simple: create the new key, move traffic to it, then revoke the old one. There's never a moment with no valid key.

The routine

  1. 1Create a new key in the dashboard with a name that says where it's used and when, such as api-server-prod-2026-10. Give it the same limits as the key it replaces.
  2. 2Store it in your secret manager under the existing secret name, so code doesn't change.
  3. 3Deploy or restart the services that read the secret. Most apps read environment variables only at start-up.
  4. 4Watch Logs and spend by key. Confirm traffic is arriving on the new key, and wait until requests on the old key stop.
  5. 5Revoke the old key. If anything still uses it, it will start getting 401 invalid_api_key, which tells you exactly what you missed.

Supporting two keys during the switch

If you run many instances that restart at different times, both keys will be in use for a while. That's fine: both are valid until you revoke one. Just don't revoke the old key until Logs show it has gone quiet.

When a key leaks

Speed matters more than tidiness. Reverse the order:

  1. 1Revoke the leaked key first. A short outage on one service is better than unbounded spend.
  2. 2Create a replacement and deploy it.
  3. 3Check spend by key in the dashboard for unusual usage before the revocation.
  4. 4Find how it leaked (a committed .env, a log line, a client bundle) and fix that, or the next key will leak the same way.

Make leaks cheap

  • One key per service and environment. Revoking the staging key shouldn't touch production.
  • A daily spend limit on every key. It caps what a leaked key can cost before anyone notices. See per-key budgets.
  • Never ship keys to clients. Browser and mobile code is readable by anyone. Call Usefully from your server.
  • Low-balance alerts. An unexpected drop in balance is often the first sign of a leaked key.

Checking which key a service uses

Keys start with a recognizable prefix (uf_live_). Log only the last four characters at start-up, never the whole key, and keep a note of which key name each service uses. When it's time to rotate, you'll know exactly which services to redeploy.

import os, logging

key = os.environ["USEFULLY_API_KEY"]
logging.info("Usefully key ...%s loaded", key[-4:])

Set a reminder to rotate every few months, and practise once on staging. Keys are managed under API keys in your organization's dashboard; if you don't have one yet, sign up.

More articles

Get started

Your first request is five minutes away.

  • $1 of free credit to start
  • No card, no subscription
  • Keep the SDK you already use
  • Real people at support@usefully.info
Rotating API keys without downtime · Usefully