/v1/workspaces/{workspace_slug}/api-keysAuthMint 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*stringSlug 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-KeystringOpaque 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*stringHuman-readable PAK name (shown in the keys list).
Example: "Production mail"
descriptionstringOptional description (e.g. which service uses the key).
Example: "Sends receipts from the checkout service."
policy_idsarrayIDs 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*stringThe full plaintext PAK token. Returned ONCE — store it now; it cannot be retrieved later.
Example: "pcft_live_abc123XYZ..."
record*objectid*string · uuidId of the key.
workspace_id*string · uuidId of the workspace the key belongs to.
created_by*string · uuidAccount id of who minted the key, or `null` when that account is gone.
name*stringName of the key.
description*stringWhat the key is for, when set.
token_prefix*stringThe first ~14 chars of the token (prefix). Plaintext token is never returned after mint.
Example: "pcft_live_abc123"
policies*arrayManaged policies currently bound to this PAK.
last_used_at*string · date-timeWhen the key last authenticated a request, or `null` if never.
revoked_at*string · date-timeWhen the key was revoked, or `null` while it is not.
expires_at*string · date-timeWhen this key stops introspecting. `null` means it never expires.
rotated_from*string · uuidId of the key this one replaced, when it was minted by a rotation.
status*objectLifecycle 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-timeWhen the key was minted.
updated_at*string · date-timeWhen 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"
}
}