# Key Rotation

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](/security/expiration-policies/).

## 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/implementation/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.

```
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, rotation may be handled for you. [Zuplo](https://zuplo.com/docs/articles/api-key-management?ref=apikeys-guide&utm_source=apikeys-guide&utm_medium=web&utm_campaign=api-keys), for example, supports key rolling with a configurable transition period: consumers can rotate keys from the developer portal or API, and the old key remains valid for a grace window you define.

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

```
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/implementation/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.