Auth API reference

Auth API · Consumer-Tenant-Api-Keys

post/{app_slug}/v1/tenant-api-keysAuth

Create an API key for the active tenant

Returns the secret ONCE (`key`). Scopes must be grantable by the app and held by your own tenant role. At most 25 active keys per tenant. If the app requires recent MFA, verify a factor first (403 `step_up_required`). Responses carry `Cache-Control: no-store`.

Path parameters

app_slug*string

The app slug.

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

name*string

Label shown in lists, 1-64 characters (e.g. `CI e2e`).

Example: "CI e2e"

scopes*array

Scopes the key carries. Each must be one of the app's grantable scopes AND held by your own tenant role (an `owner` may grant every grantable scope).

Example: ["disputes.read","audit.read"]

expires_in_daysenum (4)

Lifetime in days. One of 7, 30, 90, 365, capped by the app's `max_expiry_days`. Defaults to the app's `default_expiry_days` (90 unless configured). Keys always expire.

Example: 90

Response · 201 Key created; `key` is the 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
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "CI e2e",
  "scopes": [
    "disputes.read",
    "audit.read"
  ],
  "expires_in_days": 90
}

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