API key rotation: changing credentials without an outage

Everybody agrees keys should be rotated and almost nobody does it, because the obvious method — delete the old key, create a new one, update everything — guarantees an outage somewhere you forgot. API key rotation only becomes routine when the process allows two valid keys at once, which turns a synchronised cutover into an ordinary deployment.

The overlap method

1. Issue a second key while the first still works. Both are valid; nothing has broken yet.
2. Update consumers one at a time, verifying each before moving on.
3. Watch usage on the old key until it reaches zero, which is also how you discover the integration nobody documented.
4. Disable the old key rather than deleting it, so an unexpected failure is a one-line fix rather than a reissue.
5. Delete it after a defined quiet period, and record that you did.

Why API key rotation usually stalls

Three reasons, in order. Nobody knows where the keys are used, because they were pasted into a config during an incident two years ago. There is no usage visibility, so "is anything still using this" is unanswerable except by switching it off and waiting for complaints. And there is no owner — a key belonging to everyone belongs to nobody, and nobody volunteers to be the person who broke the nightly job. Fixing the inventory is most of fixing rotation.

One key per integration, named for what uses it. Shared keys make rotation an all-or-nothing event and make a leak unattributable — you cannot tell which system was compromised, so you have to assume all of them were.

What to do about keys you cannot account for

• Check usage first: a key with no traffic for a month is a safe candidate for disabling rather than deleting.
• Disable and wait rather than deleting — the complaint that arrives tells you what it was for, and the fix is immediate.
• Announce the window beforehand so the complaint arrives from a person rather than from a customer.
• Record what you found, because the same unknown key will otherwise be rediscovered next year.

Rotation is worthless without revocation

The point of rotating on a schedule is to limit how long a leaked credential stays useful. That only holds if revocation is genuinely immediate and genuinely complete — if a disabled key keeps working for ten minutes because of caching, your actual exposure window is the schedule plus the cache. Test revocation the same way you test backups: by doing it, once, deliberately, and confirming the request fails.

The Ettex Api issues keys scoped to a verified domain and revocable at any time, which is the property rotation depends on. Where an agent calls on your behalf through the MCP server, give it its own key for the same reason: a separate credential is what makes the blast radius answerable.