/{app_slug}/v1/tenant-api-keys/{key_id}/rotateAuthRotate an API key
Mints a replacement with the same name and scopes and returns its secret ONCE. You become the replacement's creator, so its scopes must be within your own tenant role. The outgoing key is revoked now (`grace_hours: 0`, the default) or keeps working for up to 24 hours. To kill a leaked key, revoke it. Responses carry `Cache-Control: no-store`.
Path parameters
app_slug*stringThe app slug.
key_id*stringKey id (UUID) or display id (`tak_…`).
Headers
Idempotency-KeystringRetry safety for key creation. The first request returns the secret; a repeat with the same key and body returns 409 `idempotency_secret_not_replayable` with `details.key_id` (the secret is never replayed). Same key with a different body: 409 `IDEMPOTENCY_KEY_REUSE`. 24 h window.
X-Heimdall-App-KeystringThe app's Platform API Key (`pcft_live_…`, holding `auth.tenant.api_keys.introspect` on this app). Required, next to the end user's bearer, when the app has set `management_lane: app_proxy_only`: the app's backend then proxies these routes and the end user cannot call them directly.
Request body
grace_hoursnumberHow long the OUTGOING key keeps working, in hours (0-24). `0` (the default) revokes it immediately. Rotation never lengthens the outgoing key. To get rid of a leaked key, revoke it instead.
Example: 0
expires_in_daysenum (4)Lifetime of the replacement in days (7, 30, 90, 365, capped by the app's maximum). Defaults to the original key's window.
Response · 201 Replacement created; `key` is the new secret, shown once.
id*string · uuidKey id.
display_id*stringShort public id.
Example: "tak_3a9f2b1c0d4e"
tenant_id*string · uuidTenant the key belongs to.
tenant_display_id*stringShort, human-friendly id of the tenant.
Example: "tnt_3a9f2b1c0d4e"
name*stringName of the tenant API key.
Example: "CI e2e"
key_prefix*stringFirst 16 characters of the key (environment prefix plus 6). The rest is never retrievable.
Example: "pctk_live_4fQ2aZ"
last4*stringLast 4 characters of the key.
Example: "x9Qb"
scopes*arrayScopes granted to the tenant API key.
Example: ["disputes.read"]
status*object`revoked` wins over `expired`.
created_by_account_id*string · uuidEnd user who created (or last rotated) the key. The key dies when they leave the tenant.
created_at*string · date-timeWhen the tenant API key was created (ISO 8601).
expires_at*string · date-timeWhen the tenant API key expires (ISO 8601), or `null` if it never does.
last_used_at*string · date-timeUpdated at most every 5 minutes.
revoked_at*string · date-timeWhen the tenant API key was revoked (ISO 8601), or `null` while it is active.
revoke_reason*objectWhy the tenant API key was revoked, or `null` while active.
rotated_from*string · uuidOn a replacement key, the id of the key it replaced.
key*stringThe secret, `pctk_live_…` / `pctk_test_…`. Returned exactly once: it is not stored and an `Idempotency-Key` replay does not return it again.
Example: "pctk_live_4fQ2aZ0000000000000000000000000000000000000_1a2B3c"
Example
Request
POST https://api.auth.productcraft.co/{app_slug}/v1/tenant-api-keys/{key_id}/rotate
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"grace_hours": 0,
"expires_in_days": 7
}Response
{
"id": "00000000-0000-0000-0000-000000000000",
"display_id": "tak_3a9f2b1c0d4e",
"tenant_id": "00000000-0000-0000-0000-000000000000",
"tenant_display_id": "tnt_3a9f2b1c0d4e",
"name": "CI e2e",
"key_prefix": "pctk_live_4fQ2aZ",
"last4": "x9Qb",
"scopes": [
"disputes.read"
],
"status": {},
"created_by_account_id": "00000000-0000-0000-0000-000000000000",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z",
"last_used_at": "2026-01-01T00:00:00.000Z",
"revoked_at": "2026-01-01T00:00:00.000Z",
"revoke_reason": {},
"rotated_from": "00000000-0000-0000-0000-000000000000",
"key": "pctk_live_4fQ2aZ0000000000000000000000000000000000000_1a2B3c"
}