> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).
>
> To search these docs, send a `GET` request to `https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question>` with a URL-encoded question. No authentication needed. It returns a JSON array of `{content, source_url}`, most relevant first.

# POST /api-keys/{api_key_id}/rotations

**Create an API key rotation**

Creates a rotation for an API key. Paddle generates a new secret for the key and returns it in `new_key`. The current secret keeps working. The new secret is activated the first time it's used to authenticate a request; the old secret then keeps working for `grace_period_seconds` before it stops working. Creating a rotation cancels any `pending` rotation for the same key.

Authenticate using the rotatable API key you want to rotate — a key can only rotate itself. Only API keys created as rotatable support this.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key_id` | string | required | Unique Paddle ID for this API key entity, prefixed with `apikey_`. (pattern: `^apikey_[a-z\d]{26}$`) |

## Request body

- `grace_period_seconds`: integer (required) — How long, in seconds, the old secret keeps working after the new secret is activated. The new secret is activated the first time it's used to authenticate a request. Set to `0` to stop the old secret working as soon as the new one is activated. (Range: 0–86400)
- `new_key_expires_at`: string (date-time) — RFC 3339 datetime string of when the API key should expire after this rotation. Applied when the new secret is activated. If omitted, the API key keeps its current expiry.

### Request example

```json
{
  "grace_period_seconds": 3600,
  "new_key_expires_at": "2026-11-02T00:00:00Z"
}
```

## Response (201)

- `data`: object (required) — Represents an API key rotation entity when created.
  - `id`: string (required) — Unique Paddle ID for this API key rotation entity, prefixed with `apkrot_`. (pattern: `^apkrot_[a-z\d]{26}$`)
  - `grace_period_seconds`: integer (required) — How long, in seconds, the old secret keeps working after the new secret is activated. The new secret is activated the first time it's used to authenticate a request. Set to `0` to stop the old secret working as soon as the new one is activated. (Range: 0–86400)
  - `new_key_expires_at`: string (date-time) | null (required) — RFC 3339 datetime string of when the API key should expire after this rotation. Applied when the new secret is activated. If omitted, the API key keeps its current expiry.
  - `api_key_id`: string (required) — Unique Paddle ID for this API key entity, prefixed with `apikey_`. (pattern: `^apikey_[a-z\d]{26}$`)
  - `expires_at`: string (date-time) | null (required) — RFC 3339 datetime string of when the old secret stops working. `null` until the new secret is activated.
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
  - `new_key`: string (required) — The new API key, prefixed with `pdl_` and containing `_apikey_`. Store it securely and only share with services or apps you trust. You can't retrieve it again. Once the new key is used, it becomes the primary key, and the old key will continue to work until the grace period expires. (pattern: `^pdl_(live|sdbx)_apikey_[a-z\d]{26}_[a-zA-Z\d]{22}_[a-zA-Z\d]{3}$`)
  - `status`: string (required) — Status of this API key rotation. (default: `"pending"`)
    - `pending` — Rotation was created and the new secret was issued, but it hasn't been used yet. The current secret still works.
    - `completed` — The new secret was used and is now active. The old secret works until `expires_at`.
    - `canceled` — Rotation was canceled or replaced by a newer rotation before the new secret was used.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

### Response example

```json
{
  "data": {
    "id": "apkrot_01kjnm4a3w4jqdbtqvb2jwjdf7",
    "api_key_id": "apikey_01jkdpbhazdpn3wpcya45as9tg",
    "new_key": "pdl_live_apikey_01jkdpbhazdpn3wpcya45as9tg_Wq4Hn7Kd2Lp9Vx3Tb6Mz8R_J5s",
    "grace_period_seconds": 3600,
    "new_key_expires_at": "2026-11-02T00:00:00Z",
    "expires_at": null,
    "status": "pending",
    "created_at": "2026-10-02T09:00:00.000Z",
    "updated_at": "2026-10-02T09:00:00.000Z"
  },
  "meta": {
    "request_id": "b2b4b6d7-6b7a-4b8e-9b3e-7a4d9f2a5c6e"
  }
}
```