Guide: zero-downtime key rotation
Rotate an API key without a second of failed requests, using overlapping keys and the grace period...
A key should be rotated when someone leaves, when it may have leaked, and on a schedule regardless. Here is how to do it without an outage.
The principle
Two keys are valid at once for as long as it takes to move every client from the old one to the new one. The old one is then revoked. At no point does a client hold a key that does not work.
Steps
- Create the new key in the dashboard or with
digest keys create. It is valid immediately. - Deploy the new key to every client. Use the Usage chart on the old key to see when its traffic reaches zero.
- Set a grace period on the old key:
digest keys expire <id> --in 24h. Requests still work, and each carries aWarningheader naming the key. - After the grace period, the key is revoked automatically. A request with it returns 401 with a body that says the key was rotated and when.
If the key leaked
Skip the grace period: digest keys revoke <id>. Some clients will fail until they have the new key. That is the correct trade.
Frequently Asked Questions
How often should keys rotate?
Every ninety days on a schedule, and immediately on any suspicion of a leak or when a person with access leaves.
Can two keys have different permissions during the overlap?
Yes. Rotation is a good time to narrow a key. Create the new one with the smaller scope and watch the old key's usage for calls the new one would refuse before you expire it.
Does a revoked key affect webhooks?
No. Webhook signing secrets are separate from API keys and rotate independently, with the same grace mechanism.
Release notes by email
Every release and every incident report, the day it is published. Nothing else.
Digest Engineering
The team that builds Digest. Release notes are signed by the team; incident reports by whoever was on call.
All Posts