Auth API reference

Auth API · Consumer-Tenant-Api-Keys

post/{app_slug}/v1/tenant-api-keys/introspectAuth

Verify a tenant API key (RFC 7662 shape)

For your backend: is this `pctk_` key, presented to YOUR API, usable right now, for which tenant and with which scopes? A key of another app is `{"active": false}`. Cache answers by the key's SHA-256: positives up to 30 s (never past `expires_at`), negatives up to 60 s. Intersect `scopes` with the permissions of `created_by.tenant_role` in your app. Requires `auth.tenant.api_keys.introspect` on the app. Not audited per call; `last_used_at` records use (5-minute granularity). This route has its own per-app rate bucket (1200 calls a minute by default), separate from your PAK's other calls; over it the answer is 429 with `Retry-After`, never a false `active: false`, so keep serving keys you hold a fresh positive for.

Path parameters

app_slug*string

The app slug.

Request body

key*string

The tenant API key your API received (`pctk_live_…` / `pctk_test_…`). Sent in the body, never a header. Anything that is not a well-formed key of this app is simply `{"active": false}`.

Example: "pctk_live_4fQ2aZ0000000000000000000000000000000000000_1a2B3c"

Response · 200 The verdict. Inactive is exactly `{"active": false}` for every reason.

active*boolean

`true` only for a usable key of THIS app. `false` for every other case (unknown, malformed, another app's key, revoked, expired, creator no longer a member, tenant not active, keys suspended), and then no other field is present.

key_idstring · uuid

Id of the tenant API key.

display_idstring

Short, human-friendly id of the tenant API key (shown in the console).

Example: "tak_3a9f2b1c0d4e"

tenant_idstring · uuid

The tenant the key acts for.

tenant_display_idstring

Short, human-friendly id of the tenant.

Example: "tnt_3a9f2b1c0d4e"

namestring

Name of the tenant API key.

Example: "CI e2e"

scopesarray

Scopes granted to the tenant API key.

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

created_byobject
account_id*string · uuid

End user who created (or last rotated) the key.

tenant_role*string

The creator's CURRENT role in the tenant, read live. Intersect `scopes` with this role's permissions in your app: drift can only narrow access.

Example: "agent_full"

expires_atstring · date-time

Never cache a positive answer past this instant.

envobject

`live` for keys of a production app.

Example

Request

POST https://api.auth.productcraft.co/{app_slug}/v1/tenant-api-keys/introspect
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "key": "pctk_live_4fQ2aZ0000000000000000000000000000000000000_1a2B3c"
}

Response

{
  "active": false,
  "key_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",
  "scopes": [
    "disputes.read",
    "audit.read"
  ],
  "created_by": {
    "account_id": "00000000-0000-0000-0000-000000000000",
    "tenant_role": "agent_full"
  },
  "expires_at": "2026-01-01T00:00:00.000Z",
  "env": {}
}