Platform API reference

Platform API · Platform-Api-Keys

post/v1/workspaces/{workspace_slug}/api-keysAuth

Mint a new PAK. Choose what it can do with `preset` (a ready-made set such as `mail-send`) or `policy_ids` (managed policies you wrote), never both. The plaintext `token` is returned ONCE — store it now, then call `GET /v1/api-keys/self` with it to check what it can do. The minter can grant at most their own effective permissions. Cookie/JWT only — PAKs cannot mint other PAKs. Send an `Idempotency-Key` to make a retry safe: a retry of a mint that succeeded mints nothing and answers `409 PAK_ALREADY_MINTED` with that key's `id` (the token itself is never cached).

Path parameters

workspace_slug*string

Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve("acme")`); the product APIs bind `workspace_id` instead.

Headers

Idempotency-Keystring

Opaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that deduplicates retries for 24 h. A retry with the same key and body mints nothing and answers `409 PAK_ALREADY_MINTED` with the first key's `id` in `details` (the token is shown once and never cached; rotate the key for a new one). The SDKs send one on every create.

Request body

name*string

Human-readable PAK name (shown in the keys list).

Example: "Production mail"

descriptionstring

Optional description (e.g. which service uses the key).

Example: "Sends receipts from the checkout service."

policy_idsarray

IDs of managed policies (workspace_policy rows) to bind to this PAK. Bind one or more — the PAK's effective policy is the union of all bound statements. Send exactly one of `policy_ids` and `preset`.

Example: ["11111111-1111-1111-1111-111111111111"]

presetenum (9)

A ready-made permission set to use instead of `policy_ids` (send exactly one of the two): - `mail-send` (Send email): Send email from your verified domains and check what happened to it. Cannot read message bodies or change domains. - `waitlist-write` (Waitlist sign-ups): Add and update sign-ups on your waitlists, and read the waitlists. Cannot export, delete or invite. - `trawl-jobs` (Extraction jobs): Start, cancel and read web-extraction jobs and their results. - `flags` (Manage flags): Create, edit, toggle and delete feature flags and segments in every environment, including protected ones, and manage projects and environments. Cannot reveal or rotate SDK keys, change webhooks or read confidential values. - `flags-dev` (Edit flags outside protected environments): Create and edit feature flags and segments, and change their values in environments that are not protected. Cannot touch protected environments, delete or see SDK keys. - `notify-send` (Send notifications): Send notifications, create and update recipients, mint recipient tokens for your apps and read the message log. Cannot change push credentials, notification types, settings or webhooks. - `notify-readonly` (Notify read-only): Read recipients, notification types, channels, settings, webhooks and the message log. Changes nothing and sends nothing. - `readonly` (Read-only): Read-only across the workspace: settings, members, email, waitlists, communities, web-extraction jobs, feature flags and notifications. Changes nothing. - `full` (Full access): Every action this workspace exposes, except creating keys, editing roles and policies, and other actions that hand out access. Use a custom policy for those. The first key minted with a preset creates a managed policy for it in this workspace (named "<label> preset", `preset_key` set); later keys reuse that policy, so editing it changes every key bound to it. When the definition of a preset grows (a new product, for example), existing preset policies are updated to match, unless an owner has edited their statements. `readonly` and `full` are the same permission sets as the MCP connection presets of the same name. No preset can create keys, edit roles or policies, or hand out other access.

Example: "mail-send"

expires_in_daysenum (3)

Lifetime of the key in days. Omit or send `null` for a key that never expires — the historical behaviour, what every PAK minted before this field existed holds, and still the default. Enforced at introspection: past `expires_at` the key resolves to 401 exactly like a revoked one.

Example: 90

Response · 201

token*string

The full plaintext PAK token. Returned ONCE — store it now; it cannot be retrieved later.

Example: "pcft_live_abc123XYZ..."

record*object
id*string · uuid

Id of the key.

workspace_id*string · uuid

Id of the workspace the key belongs to.

created_by*string · uuid

Account id of who minted the key, or `null` when that account is gone.

name*string

Name of the key.

description*string

What the key is for, when set.

token_prefix*string

The first ~14 chars of the token (prefix). Plaintext token is never returned after mint.

Example: "pcft_live_abc123"

policies*array

Managed policies currently bound to this PAK.

last_used_at*string · date-time

When the key last authenticated a request, or `null` if never.

revoked_at*string · date-time

When the key was revoked, or `null` while it is not.

expires_at*string · date-time

When this key stops introspecting. `null` means it never expires.

rotated_from*string · uuid

Id of the key this one replaced, when it was minted by a rotation.

status*object

Lifecycle state at the time of the request. Only `active` keys introspect. `revoked` beats `expired` — revocation is a deliberate act by a named actor and the row keeps saying so.

created_at*string · date-time

When the key was minted.

updated_at*string · date-time

When the key was last changed.

Example

Request

POST https://api.platform-auth.productcraft.co/v1/workspaces/{workspace_slug}/api-keys
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "Production mail",
  "description": "Sends receipts from the checkout service.",
  "policy_ids": [
    "11111111-1111-1111-1111-111111111111"
  ],
  "preset": "mail-send",
  "expires_in_days": 90
}

Response

{
  "token": "pcft_live_abc123XYZ...",
  "record": {
    "id": "00000000-0000-0000-0000-000000000000",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_by": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string",
    "token_prefix": "pcft_live_abc123",
    "policies": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "mail-readonly",
        "description": "string"
      }
    ],
    "last_used_at": "2026-01-01T00:00:00.000Z",
    "revoked_at": "2026-01-01T00:00:00.000Z",
    "expires_at": "2026-01-01T00:00:00.000Z",
    "rotated_from": "00000000-0000-0000-0000-000000000000",
    "status": {},
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
}