Rotating API keys without downtime

What rotation actually does

Calling POST /api/v1/keys/rotate against your current key issues a brand new key immediately and returns it in the response body, shown once, exactly like at creation. It does not invalidate the old key on the spot. Instead, the response also includes oldKeyValidUntil, a timestamp 24 hours out, during which both the old and new key work side by side.

That overlap window is the entire point. It means rotation is something you can do proactively on a schedule, on suspicion of exposure, or as part of routine credential hygiene, without needing to coordinate a single cutover moment across every server, container, and scheduled job that holds a copy of the key.

The 24 hour grace period

For 24 hours after rotation, requests authenticated with either the old or the new key succeed normally. Nothing about rate limits, plan, or credit balance changes during this window, both keys are simply two valid credentials for the same account. Once oldKeyValidUntil passes, the old key starts returning 401 on every request, with no further grace and no automatic extension.

The clock starts at the moment you call the rotate endpoint, not at the moment you finish updating your systems, so the useful strategy is to rotate first and then work through your deployment targets methodically, rather than trying to prepare every server in advance and rotate at the last second.

A rollout order that never drops a request

• Call POST /api/v1/keys/rotate and store the new key immediately in your secrets manager. It's shown exactly once, the same as at creation, so treat the response the same way you would a freshly created key.
• Update servers, containers, and scheduled jobs one at a time or in small batches, redeploying each with the new key, while the old key still works for everything not yet updated.
• Confirm each updated target is actually using the new key by checking its logs or making a test request, rather than assuming a deploy succeeded.
• Once every target is confirmed on the new key, there's no need to wait out the rest of the 24 hours, the old key simply stops being used and its eventual expiry is a formality.
• If you can't confirm every target before the grace period ends, prioritize checking GET /api/v1/usage or your error logs right after oldKeyValidUntil passes, a sudden run of 401s is the signal that something was missed.

Rotating on a schedule versus rotating on suspicion

Routine rotation, say every 90 days as a hygiene practice, is low pressure: you have the full 24 hours and no reason to rush, so the batch-by-batch rollout above works comfortably. Rotating because a key may have leaked, in a log, a public repository, a shared screen, is different in urgency but not in mechanism. The same endpoint and the same grace period apply either way.

The one thing worth doing differently under suspicion of exposure is treating the old key as compromised for the entire grace period, not just eventually. If you have reason to believe someone else has the old key, monitor GET /api/v1/usage during those 24 hours for request volume you don't recognize, since the old key remains fully functional for anyone holding it until it expires.

What rotation doesn't affect

Rotation only replaces the credential. It doesn't touch your plan, included credits, carried-over credits, rate limits, or any tracked codes and campaigns created under the account. Everything keyed to your account rather than to the specific key string keeps working exactly as before, on both the old and new key, for the duration of the overlap.

It's also worth knowing that failed authentication attempts are rate-limited separately, at 10 per minute per IP address, regardless of which key is being tried. A server left retrying an expired old key in a tight loop after the grace period ends can trip this limit and start seeing 429s on top of the expected 401s, which looks confusing but is really just a symptom of the same missed update.

Frequently asked questions

Related guides