# Guide: zero-downtime key rotation Author: Digest Engineering Author URL: https://dmeodigest.superblog.click/author/digest-engineering/ Published: 2026-08-08 Category: Guides Category URL: https://dmeodigest.superblog.click/category/guides/ Meta Title: Guide: zero-downtime key rotation ยท Digest Meta Description: Rotate an API key without a second of failed requests, using overlapping keys and the grace period. Tags: guide, security, api keys Tag URLs: guide (https://dmeodigest.superblog.click/tag/guide/), security (https://dmeodigest.superblog.click/tag/security/), api keys (https://dmeodigest.superblog.click/tag/api-keys/) URL: https://dmeodigest.superblog.click/guide-zero-downtime-key-rotation/ ![A keyboard in low light](https://images.unsplash.com/photo-1598662779094-110c2bad80b5?ixid=M3w3OTAzOTJ8MHwxfHNlYXJjaHw3fHxrZXlib2FyZCUyMGNsb3NlJTIwdXAlMjBkYXJrfGVufDF8MHx8fDE3ODg2Mzg0NTR8MA&ixlib=rb-4.1.0&w=1600&q=80&auto=format&fit=crop) 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 1. Create the new key in the dashboard or with `digest keys create`. It is valid immediately. 2. Deploy the new key to every client. Use the Usage chart on the old key to see when its traffic reaches zero. 3. Set a grace period on the old key: `digest keys expire --in 24h`. Requests still work, and each carries a `Warning` header naming the key. 4. 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 `. Some clients will fail until they have the new key. That is the correct trade. ## FAQs Q: How often should keys rotate? A: Every ninety days on a schedule, and immediately on any suspicion of a leak or when a person with access leaves. Q: Can two keys have different permissions during the overlap? A: 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. Q: Does a revoked key affect webhooks? A: No. Webhook signing secrets are separate from API keys and rotate independently, with the same grace mechanism. --- This blog is powered by Superblog. Visit https://superblog.ai to know more. ---