---
title: "Create a replacement key and schedule old-key revocation"
method: POST
path: "/api-keys/{keyId}/rotate"
tags: ["API Keys"]
---

# Create a replacement key and schedule old-key revocation

`POST /api-keys/{keyId}/rotate`

## Request

- Base URL: `https://api.flashdata.dev/v2`
- URL: `https://api.flashdata.dev/v2/api-keys/{keyId}/rotate`
- Auth: API key in cookie `__Host-fd_session` and API key in header `X-CSRF-Token`

The old key remains active during a bounded overlap window. Omitting
`revokeOldAt` uses a 24-hour overlap, capped by the old key expiry.
An explicit value must be in the future, no more than seven days from
the request, and no later than the old key expiry. Internal primary and
retiring rotation states are not exposed as public API Key statuses.

## Path parameters

- `keyId` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `revokeOldAt` string, date-time: Optional old-key revocation time; defaults to 24 hours and cannot exceed seven days or the old key expiry.

## Response `201`

Replacement created; secret returned once

- ApiKeyCreated
  - `apiKey` ApiKey, required: Public API Key metadata. Internal primary/retiring rotation state is intentionally omitted; a retiring key remains `active` until scheduledRevocationAt.
    - `id` string, required
    - `name` string, required
    - `prefix` string, required
    - `last4` string, required
    - `scopes` string[], required
    - `status` 'active' | 'revoked' | 'expired', required
    - `lastUsedAt` string, date-time, nullable
    - `expiresAt` string, date-time, nullable
    - `scheduledRevocationAt` string, date-time, nullable: Planned revocation time for an overlapping retiring key; null for a primary or immediately revoked key.
    - `createdAt` string, date-time, required
  - `secret` string, required: Plaintext secret returned only by this create/rotate transaction. Newly issued secrets use the `fd_` prefix. Previously issued `fd_test_` and `fd_live_` secrets still authenticate. An authenticated replay with the same Idempotency-Key and request body may receive the same KMS-encrypted response for five minutes; it is not recoverable afterward.

## Other responses

- `401`: Authentication required or invalid
- `403`: Authenticated but not permitted, or CSRF validation failed
- `404`: Resource not found or not owned by the caller
- `409`: Resource state or idempotency conflict
- `422`: Request validation failed
- `503`: A required dependency or catalog is temporarily unavailable

---

[API](https://skmtc.dev/flashdata/apis/flashdata-customer-api.md) · [All operations](https://skmtc.dev/flashdata/apis/flashdata-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flashdata/apis/flashdata-customer-api/revisions/109179fe9313?raw)