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
- 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. - 2Store it in your secret manager under the existing secret name, so code doesn't change.
- 3Deploy or restart the services that read the secret. Most apps read environment variables only at start-up.
- 4Watch Logs and spend by key. Confirm traffic is arriving on the new key, and wait until requests on the old key stop.
- 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:
- 1Revoke the leaked key first. A short outage on one service is better than unbounded spend.
- 2Create a replacement and deploy it.
- 3Check spend by key in the dashboard for unusual usage before the revocation.
- 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.