# Key Rotation

<span class="akg-updated" data-updated="2026-04-22">Updated April 2026</span>

Rotation is about proactively replacing a key before it is compromised, distinct from time-based expiration where a key simply stops working at a set deadline. For automatic expiration policies, see [Expiration Policies](/docs/security/expiration-policies).

<TLDR>

- Rotation means proactively replacing a key before it's compromised; expiration means the key dies on a schedule. You usually want both.
- Support multiple active keys per consumer at the same time, so old and new keys overlap during the transition and nobody has downtime.
- Grace windows should match the consumer: hours for internal microservices, weeks for third-party partners, months for public developer ecosystems.
- Automate the lifecycle via a secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager) so rotation stops being an event and becomes background maintenance.
- Proactive notifications (email, response headers, dashboard) matter more than you think. Surprise expirations produce the outages rotation is supposed to prevent.

</TLDR>

## Why Rotation Matters

API keys are long-lived credentials. The longer a key exists, the greater the chance it has been logged, committed to a repo, shared in a chat, or [exfiltrated by an attacker](/docs/security/leak-detection). Regular rotation limits the window of exposure. Even if a key is compromised, it becomes useless once rotated out.

Rotation is also a compliance requirement in many frameworks. PCI-DSS, SOC 2, and ISO 27001 all expect periodic credential rotation as part of a healthy security posture.

## The Overlap Strategy

The most important principle of key rotation is that the old key and the new key must both work at the same time. If you invalidate the old key the instant the new one is created, every client using the old key breaks simultaneously.

An overlap (or grace) period gives consumers time to update their configuration:

1. **Generate** a new key and store it alongside the old one.
2. **Notify** the consumer that a new key is available and that the old key will expire at a specific time.
3. **Wait** for the grace period (hours, days, or weeks depending on your use case).
4. **[Revoke](/docs/security/revocation)** the old key after the grace period ends.

During the overlap window, both keys authenticate successfully. Your validation logic should check all active keys for a given consumer, not just the most recent one.

```text
Timeline:
|--- Old key active ---|--- Grace period (both keys work) ---|--- Old key revoked ---|
                       ^                                      ^
                   New key issued                       Old key expires
```

## Grace Period Guidelines

The right grace period depends on how your API is consumed:

| Consumer Type | Suggested Grace Period |
|---|---|
| Internal microservices | 1-24 hours |
| Third-party integrations | 7-14 days |
| Mobile / IoT clients | 14-30 days |
| Public developer ecosystem | 30-90 days |

Shorter is better from a security standpoint, but you need to balance that against the operational reality of how quickly consumers can deploy changes.

## Automated Rotation

Manual rotation doesn't scale. For internal services, automate the full lifecycle:

1. A scheduled job generates a new key and writes it to your secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager).
2. The application reads the current key from the secrets manager on each request, so no redeployment is needed.
3. After the grace period, another job deletes the old key.

If you use a managed API key platform or secrets manager, rotation may be handled for you. HashiCorp Vault, AWS Secrets Manager, and Doppler each automate the secret side of rotation, and gateway platforms like Zuplo extend that to the consumer side. Zuplo's [roll-key endpoint](https://zuplo.com/docs/articles/api-key-leak-detection?ref=apikeys-guide&utm_source=apikeys-guide&utm_medium=web&utm_campaign=api-keys) generates a new key for a consumer and sets an `expiresOn` timestamp on existing keys; consumers can trigger the same flow from the developer portal, and the old key remains valid until the expiration you configure.

For external consumers who manage keys directly, provide a self-service rotation endpoint:

```http
POST /v1/api-keys/rotate
Authorization: Bearer {current_key}
```

This endpoint should:

- Generate a new key.
- Return the new key in the response body (the only time the plaintext key is exposed).
- Set the old key's expiration to `now + grace_period`.
- Return the expiration timestamp so the consumer knows their deadline.

```json
{
  "key": "sk_live_new_key_value_here",
  "previous_key_expires_at": "2026-05-14T00:00:00Z"
}
```

## Notification Patterns

Don't rely on consumers checking a dashboard. Proactive notifications reduce the risk of outages during rotation:

- **Email / webhook** when a new key is issued.
- **Warning headers** on API responses when the current key is approaching expiration: `X-Api-Key-Expires: 2026-05-14T00:00:00Z`.
- **Dashboard alerts** in your developer portal.
- **Escalation** if the old key is still being used within 24 hours of expiration (email the account owner directly).

## Zero-Downtime Rotation Checklist

- [ ] Allow multiple active keys per consumer at the same time.
- [ ] Define a grace period that matches your consumer base.
- [ ] Automate rotation for internal services using a secrets manager.
- [ ] Provide a self-service rotation endpoint for external consumers.
- [ ] Send proactive notifications at key issuance and approaching expiration.
- [ ] Log which key was used on each request so you can tell when the old key is no longer in use.
- [ ] [Revoke](/docs/security/revocation) the old key only after confirming zero traffic or after the grace period expires.

Rotation is not a one-time event. Build it into your API platform from the start, and it becomes a routine operational task rather than a fire drill.

<HowTo
  name="Rotate an API key with zero downtime"
  description="Issue a replacement key, cut traffic over, and retire the old key only once it is idle, all without dropping a single request."
  totalTime="P14D"
  steps={[
    { name: "Issue a replacement key. ", text: "Create a new key for the same consumer with identical scopes, record a rotation-of reference to the outgoing key, and mark both as simultaneously active." },
    { name: "Distribute the new key. ", text: "Deliver the new key to the consumer via your secrets manager, rotation endpoint, or an out-of-band notification. For internal services, a secrets manager with a restart hook makes this a deploy-free change." },
    { name: "Observe both keys in parallel. ", text: "Log which key was used on each request. When traffic on the old key drops to zero for a sustained period (or the grace window closes), you know migration is complete." },
    { name: "Notify before expiry. ", text: "Send proactive warnings at issuance, at 50% and 90% of the grace period, and attach an X-Api-Key-Expires header to every response made with the old key so automated consumers can react." },
    { name: "Revoke the old key. ", text: "Once traffic is zero or the grace period expires, mark the old key revoked so any surviving copy stops working immediately.", url: "https://apikeys.guide/docs/security/revocation" },
  ]}
/>

## References

- [NIST SP 800-57 Part 1 Rev. 5: Recommendation for Key Management](https://csrc.nist.gov/publications/detail/sp/800-57-part-1/rev-5/final): the authoritative reference on cryptoperiods, key states, and why rotation is necessary even for healthy keys.
- [NIST SP 800-63B: Digital Identity Guidelines §5.1.1](https://pages.nist.gov/800-63-3/sp800-63b.html#memsecret): authenticator lifecycle requirements including periodic renewal.
- [OWASP Secrets Management Cheat Sheet: Rotation](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html#8-secrets-lifecycle): operational guidance on scheduling and automating rotation for secrets like API keys.
- [OWASP Authentication Cheat Sheet: Changing passwords](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#changing-passwords): related guidance on credential updates and overlap windows.
- [Google Cloud: Rotate API keys](https://cloud.google.com/docs/authentication/api-keys#rotate): a reference rotation workflow that uses overlapping keys and scheduled deprecation.
- [CWE-613: Insufficient Session Expiration](https://cwe.mitre.org/data/definitions/613.html): the weakness that long-lived, never-rotated credentials fall into.