/{app_slug}/v1/tenant-api-keysAuthCreate 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*stringThe app slug.
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
name*stringLabel shown in lists, 1-64 characters (e.g. `CI e2e`).
Example: "CI e2e"
scopes*arrayScopes 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 · 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
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"
}