Auth API reference

Auth API · Consumer-Tenant-Api-Keys

post/{app_slug}/v1/tenant-api-keys/{key_id}/rotateAuth

Rotate 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*string

The app slug.

key_id*string

Key id (UUID) or display id (`tak_…`).

Headers

Idempotency-Keystring

Retry 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-Keystring

The 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_hoursnumber

How 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 · uuid

Key id.

display_id*string

Short public id.

Example: "tak_3a9f2b1c0d4e"

tenant_id*string · uuid

Tenant the key belongs to.

tenant_display_id*string

Short, human-friendly id of the tenant.

Example: "tnt_3a9f2b1c0d4e"

name*string

Name of the tenant API key.

Example: "CI e2e"

key_prefix*string

First 16 characters of the key (environment prefix plus 6). The rest is never retrievable.

Example: "pctk_live_4fQ2aZ"

last4*string

Last 4 characters of the key.

Example: "x9Qb"

scopes*array

Scopes granted to the tenant API key.

Example: ["disputes.read"]

status*object

`revoked` wins over `expired`.

created_by_account_id*string · uuid

End user who created (or last rotated) the key. The key dies when they leave the tenant.

created_at*string · date-time

When the tenant API key was created (ISO 8601).

expires_at*string · date-time

When the tenant API key expires (ISO 8601), or `null` if it never does.

last_used_at*string · date-time

Updated at most every 5 minutes.

revoked_at*string · date-time

When the tenant API key was revoked (ISO 8601), or `null` while it is active.

revoke_reason*object

Why the tenant API key was revoked, or `null` while active.

rotated_from*string · uuid

On a replacement key, the id of the key it replaced.

key*string

The 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"
}