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

# Rotate API Key

> Replace a child's API key with a new one. The old key is revoked immediately.

Mints a replacement key with the same scope and constraints as the original, then **revokes the old key immediately** — there is no grace window on this surface. Use your **parent** key with `accounts.write`. A sandbox key is re-minted as a sandbox key (`trk_test_` prefix).

<Warning>
  The old key stops working the moment rotation completes. Deploy the new key before rotating. The new plaintext `key` is returned **once** in this response.
</Warning>

## Path Parameters

<ParamField path="child_id" type="integer" required>
  The child account's `accountId`.
</ParamField>

<ParamField path="key_id" type="string" required>
  The `id` of the key to rotate.
</ParamField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.tracklysms.com/api/v2/accounts/children/1042/api-keys/66b0f7c84a1d4b2e9c3a1f2e/rotate \
    -H "X-Api-Key: trk_your_parent_key"
  ```
</RequestExample>

<ResponseExample>
  ```json Success (201) theme={null}
  {
    "apiKey": {
      "id": "66c1a8d95b2e4c3f0d4b2e6f",
      "accountId": 1042,
      "name": "prod",
      "key": "trk_zy98xw76vu54ts32rq10po98nm76lk54",
      "keyPrefix": "trk_zy98",
      "status": "active",
      "permissions": ["api.full"],
      "sandbox": false,
      "rotatedFrom": "66b0f7c84a1d4b2e9c3a1f2e",
      "createdAt": "2026-07-26T16:00:00.000000",
      "lastUsedAt": null
    },
    "message": "Store the plaintext key now — it cannot be retrieved later."
  }
  ```
</ResponseExample>

## Error Codes

| HTTP Status | Error Code                                               | Description                                             |
| ----------- | -------------------------------------------------------- | ------------------------------------------------------- |
| 404         | `child_not_found` / `key_not_found`                      | No such child or key.                                   |
| 409         | `key_not_active`                                         | The key is already revoked or expired.                  |
| 409         | `rotate_conflict`                                        | A concurrent rotation is in progress.                   |
| 409         | `child_deleted`                                          | The child has been deleted.                             |
| 403         | `invalid_permission` / `constrained_key_cannot_delegate` | The caller cannot re-mint this key's scope.             |
| 502         | `rotate_failed`                                          | The rotation could not be completed (transient); retry. |

<Note>
  This rotates the **API key**. To rotate a webhook endpoint's **signing secret** (which keeps a 24-hour grace window), see [Webhook Signing](/api-reference/v2/webhooks/signing#rotating-the-signing-secret).
</Note>