curl -X POST https://api.tracklysms.com/api/v2/accounts/children/1042/api-keys/66b0f7c84a1d4b2e9c3a1f2e/rotate \
-H "X-Api-Key: trk_your_parent_key"
{
"apiKey": {
"id": "66c1a8d95b2e4c3f0d4b2e6f",
"accountId": 1042,
"name": "prod",
"key": "trk_zy98xw76vu54ts32rq10po98nm76lk54",
"keyPrefix": "trk_zy98",
"status": "active",
"permissions": ["api.full"],
"resourceConstraints": {},
"expiresAt": null,
"allowedIps": [],
"rateLimitOverride": null,
"sandbox": false,
"graceUntil": null,
"rotatedFrom": "66b0f7c84a1d4b2e9c3a1f2e",
"lastUsedIp": null,
"createdAt": "2026-07-26T16:00:00.000000",
"lastUsedAt": null
},
"message": "Store the plaintext key now — it cannot be retrieved later."
}
Partner Accounts (v2)
Rotate API Key
Replace a child’s API key with a new one. The old key is revoked immediately.
POST
/
v2
/
accounts
/
children
/
{child_id}
/
api-keys
/
{key_id}
/
rotate
curl -X POST https://api.tracklysms.com/api/v2/accounts/children/1042/api-keys/66b0f7c84a1d4b2e9c3a1f2e/rotate \
-H "X-Api-Key: trk_your_parent_key"
{
"apiKey": {
"id": "66c1a8d95b2e4c3f0d4b2e6f",
"accountId": 1042,
"name": "prod",
"key": "trk_zy98xw76vu54ts32rq10po98nm76lk54",
"keyPrefix": "trk_zy98",
"status": "active",
"permissions": ["api.full"],
"resourceConstraints": {},
"expiresAt": null,
"allowedIps": [],
"rateLimitOverride": null,
"sandbox": false,
"graceUntil": null,
"rotatedFrom": "66b0f7c84a1d4b2e9c3a1f2e",
"lastUsedIp": null,
"createdAt": "2026-07-26T16:00:00.000000",
"lastUsedAt": null
},
"message": "Store the plaintext key now — it cannot be retrieved later."
}
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
The replacement key inherits the old key’s
accounts.write. A sandbox key is re-minted as a sandbox key (trk_test_ prefix).
An otherwise unrestricted parent may rotate child keys when its list_numbers constraint is omitted, null, or an empty list. Active list restrictions, malformed or unsupported stored constraints, an IP allowlist, a daily cap, or required send confirmation block delegation.
Rotation rechecks parent authority together with the child-key change. Concurrent parent revocation, policy changes, or account ownership changes refuse the rotation with 409 rotate_conflict.
The old key stops working the moment rotation completes. Prepare your integration to install the replacement immediately after this response. The new plaintext
key is returned once.Path Parameters
integer
required
The child account’s
accountId.string
required
The
id of the key to rotate.Examples
curl -X POST https://api.tracklysms.com/api/v2/accounts/children/1042/api-keys/66b0f7c84a1d4b2e9c3a1f2e/rotate \
-H "X-Api-Key: trk_your_parent_key"
{
"apiKey": {
"id": "66c1a8d95b2e4c3f0d4b2e6f",
"accountId": 1042,
"name": "prod",
"key": "trk_zy98xw76vu54ts32rq10po98nm76lk54",
"keyPrefix": "trk_zy98",
"status": "active",
"permissions": ["api.full"],
"resourceConstraints": {},
"expiresAt": null,
"allowedIps": [],
"rateLimitOverride": null,
"sandbox": false,
"graceUntil": null,
"rotatedFrom": "66b0f7c84a1d4b2e9c3a1f2e",
"lastUsedIp": null,
"createdAt": "2026-07-26T16:00:00.000000",
"lastUsedAt": null
},
"message": "Store the plaintext key now — it cannot be retrieved later."
}
resourceConstraints, dailySendCap, requireSendConfirmation, expiresAt, allowedIps, and rateLimitOverride. It shares the original key’s daily send usage. A later dashboard change to its allowed lists, daily cap, or confirmation setting revokes other still-valid credentials from the same rotation chain.
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 has been revoked or is pending deletion. A past-expiry key can still be rotated — the replacement inherits the same expiresAt. |
| 409 | rotate_conflict | The child key, parent authority, or account ownership changed concurrently. Reload the current configuration before rotating. |
| 409 | api_key_outcome_unknown | Rotation could not be confirmed. No plaintext is returned. Do not retry; contact support with the response’s supportReference. |
| 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. |
| 503 | api_key_lineage_unavailable | The key’s rotation history could not be validated. Contact support before retrying. |
This rotates the API key. To rotate a webhook endpoint’s signing secret (which keeps a 24-hour grace window), see Webhook Signing.