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

# Rotate an API key

> Create a replacement key with a bounded rollout grace period.

Requires an authenticated dashboard session. Returns `201 Created`.

<ParamField path="workspace_id" type="uuid" required>
  Workspace that owns the current key.
</ParamField>

<ParamField path="key_id" type="uuid" required>
  Key metadata identifier to replace.
</ParamField>

<ParamField body="grace_seconds" default="86400" type="integer" required>
  Time the old key may remain valid while consumers roll over. Minimum 0; maximum 604,800 seconds (seven days).
</ParamField>

## Response

<ResponseField name="key" type="string" required>
  Replacement plaintext `ig_live_` secret. Returned only once.
</ResponseField>

<ResponseField name="replacement_for_key_id" type="uuid | null" required>
  ID of the key this credential replaces.
</ResponseField>

<ResponseField name="rotation_grace_expires_at" type="string | null" required>
  Timestamp after which the old key is no longer valid.
</ResponseField>

<Steps>
  <Step title="Store the replacement">
    Write the one-time secret to your server-side secret manager.
  </Step>

  <Step title="Deploy consumers">
    Update every service before the grace window closes.
  </Step>

  <Step title="Verify and revoke">
    Confirm the new prefix is in use, then revoke the old key early when safe.
  </Step>
</Steps>


## Related topics

- [Revoke an API key](/reference/api-keys/revoke.md)
- [List API keys](/reference/api-keys/list.md)
- [Create an API key](/reference/api-keys/create.md)
- [Authentication](/authentication.md)
- [Security model](/security.md)