> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strait.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Key Rotation

> Rotate keys with grace windows for zero-downtime credential rollovers.

Strait supports API key rotation with grace periods.

## Endpoint

* `POST /v1/api-keys/{keyID}/rotate`

<Note>
  CLI parity is supported via `strait api-keys rotate --grace-period-minutes <n>` which uses the same API rotation endpoint.
</Note>

## Request

```json theme={null}
{
  "name": "ci-key-2026-03",
  "grace_period_seconds": 3600
}
```

## Behavior

* New key is created and returned once.
* Previous key is marked with:
  * `replaced_by_key_id`
  * `grace_expires_at`
* Old key remains temporarily valid until grace expires.
* After grace expiry, old key authentication fails.

## Recommended Rotation Flow

1. Rotate key with a grace window.
2. Roll out new key to all clients.
3. Verify traffic uses the new key.
4. Let grace expire (or revoke old key explicitly).

## Security Notes

* Store only the returned raw key in your secret manager.
* Never log raw keys.
* Keep grace windows short.

See [Authentication & Authorization](/guides/authentication) and [CLI API Keys](/cli/api-keys).