# Rotate a key

`POST /api/api-keys/{id}/rotate`  (operationId: `rotateApiKey`, group: API keys)

Issues a replacement with the same scopes, limit and label, and ends the old key. Set grace_hours (up to 168) to keep the old key valid while a deployed integration switches over; 0 revokes it at once. The new plaintext is shown once.

Part of the full API, which is included in the Scale plan. Workspace admin: a dashboard session, or a full-access key created by an admin. A scoped key is refused with scope_denied.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Key id. |

**Request body** (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `grace_hours` | integer | no | Range 0..168. |

Example:

```json
{
  "grace_hours": 24
}
```

**Response 200**: OK (schema `ApiKeyRotated`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer |  |
| `label` | string |  |
| `key` | string | The new plaintext key. Shown once. |
| `last_4` | string |  |
| `scopes` | array of string |  |
| `rotated_from` | integer |  |
| `old_key_valid_until` | string (date-time), nullable | Set when grace_hours was used. |
| `message` | string |  |

Example:

```json
{
  "id": 8,
  "label": "Dashboard",
  "key": "iwk_9pQ2m8...t3Lw",
  "last_4": "t3Lw",
  "scopes": [
    "inbox:read",
    "team_management:read"
  ],
  "rotated_from": 7,
  "old_key_valid_until": "2026-10-03T10:00:00.000Z",
  "message": "Save this key now. It can’t be shown again."
}
```

**Errors specific to this call.** The common ones (401, 403, 429 and the rest) are in the [Errors guide](https://inboxwa.online/docs/api/guide/errors.md).

| Status | error | When |
| --- | --- | --- |
| 400 | `invalid_grace` | grace_hours outside 0 to 168. |
| 404 | `not_found` | No such key. |
| 400 | `already_revoked` | The key is already revoked. |

Part of the InboxWA API reference: https://inboxwa.online/docs/api . Full reference as one document: https://inboxwa.online/docs/api.md . OpenAPI: https://inboxwa.online/openapi.json