Auth API reference

Auth API · Consumer-Tenant-Api-Keys

put/{app_slug}/v1/tenant-api-keys/configAuth

Push this app's tenant API key settings

Call it on boot: your code is the source of truth for the scopes a key can carry. Fields you leave out keep their stored value. `suspended` is the platform's kill switch: this route never changes it, and a body that carries it is refused. Requires `auth.tenant.api_keys.configure` on the app.

Path parameters

app_slug*string

The app slug.

Headers

Idempotency-Keystring

Retry safety. Same key and body within 24 h replays the first response; same key with a different body is 409 `IDEMPOTENCY_KEY_REUSE`.

Request body

enabledboolean

Turn tenant API keys on for this app. Needs at least one grantable scope.

grantable_scopesarray

The scopes a key of this app can carry. Replaces the stored list. At most 64, unique.

manage_rolesarray

Tenant roles (this app's role names, case-insensitive) whose members may create, rotate and revoke keys. Default `['owner']`.

Example: ["owner"]

management_laneenum (2)

`direct`: an end user's bearer alone can manage keys. `app_proxy_only`: the bearer is accepted only together with this app's PAK in `X-Heimdall-App-Key`, so every change passes through your backend.

default_expiry_daysenum (4)

Lifetime when the creator names none. At most `max_expiry_days`.

max_expiry_daysenum (4)

Longest lifetime a key may have.

require_recent_mfa_minutesinteger

When set, creating or rotating a key needs a second factor verified within this many minutes. `null` switches it off.

Response · 200 The settings now stored.

enabled*boolean

Effective: `false` whenever there is no grantable scope.

grantable_scopes*array

The scopes a tenant API key of this app can carry.

manage_roles*array

Tenant roles whose members may create, rotate and revoke keys.

Example: ["owner"]

management_lane*object

`direct`: an end user's bearer alone can manage keys. `app_proxy_only`: only together with the app's PAK in `X-Heimdall-App-Key`.

default_expiry_days*object

Lifetime in days when the creator names none.

max_expiry_days*object

Longest lifetime in days a key may have.

require_recent_mfa_minutes*integer

When set, creating or rotating a key needs a second factor verified within this many minutes; `null` when off.

suspended*boolean

Platform kill switch (console / Auth-admin only).

pushed_by_app_at*string · date-time

When the app's own backend last pushed this config (`PUT /:appSlug/v1/tenant-api-keys/config`); `null` if it never has. Set by the server, never by a request. While set, the console treats the app's fields as owned by the app's code and shows them read-only; `suspended` stays the platform's.

Example

Request

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

{
  "enabled": false,
  "grantable_scopes": [
    {
      "name": "disputes.read",
      "description": "Read disputes"
    }
  ],
  "manage_roles": [
    "owner"
  ],
  "management_lane": "direct",
  "default_expiry_days": 7,
  "max_expiry_days": 7,
  "require_recent_mfa_minutes": 0
}

Response

{
  "enabled": false,
  "grantable_scopes": [
    {
      "name": "disputes.read",
      "description": "Read disputes"
    }
  ],
  "manage_roles": [
    "owner"
  ],
  "management_lane": {},
  "default_expiry_days": {},
  "max_expiry_days": {},
  "require_recent_mfa_minutes": 0,
  "suspended": false,
  "pushed_by_app_at": "2026-01-01T00:00:00.000Z"
}