Getting started

Your first Platform API call.

Five minutes. From the console to a working CI/CD integration.

Step 1

Sign in + pick a workspace

Open auth.productcraft.co. If you don't have a ProductCraft account yet, sign up — every product on this platform shares the same account. Once signed in, create a workspace or open an existing one. The workspace is the boundary for everything you can do programmatically — its domains, mailboxes, Auth apps, Waitlist waitlists, members, roles, and audit log.

Your role on the workspace caps what any API key you mint can do: the minter can never grant more than their own effective permissions. Minting requires workspace.apikey.create — owners and admins have it by default; members don't.

Step 2

Mint a workspace API key

In the console, open your workspace's API keys page and click New API key. Name it, bind one or more policies, and copy the token — it's only shown once. Policies are authored on the Policies page (owner-only); each one is a list of allow/deny statements.

example policy statement (read-only audit)

[
  {
    "effect": "allow",
    "actions": ["workspace.audit.read", "workspace.member.read"],
    "resources": ["*"]
  }
]

The token shape is pcft_live_<random>. Treat it like a password — store it in your CI secret store, never commit it. Keys never expire automatically; revoke them when the use case ends. Only a signed-in human can mint — a key cannot mint other keys.

Step 3

Verify the token

The /v1/introspect endpoint identifies your bearer. Use it as a one-call check that the token is live and bound to the workspace you expect.

curl

curl https://api.platform-auth.productcraft.co/v1/introspect \
  -H "Authorization: Bearer pcft_live_..."

A 200 confirms the token works: the body shows the principal ("type": "pak") and the workspace the key belongs to, with its enabled services. A 401 means the token is invalid, revoked, or malformed.

Step 4

Provision an Auth app from CI

The canonical CI/CD use case: your deploy pipeline needs an Auth app for the environment it's building. The Platform API lets that happen without a human in the loop.

provision script

#!/usr/bin/env bash
set -euo pipefail
KEY="${PRODUCTCRAFT_API_KEY}"   # pcft_live_...
WS_ID="${WORKSPACE_ID}"         # workspace UUID

# 1. Create the Auth app (needs auth.create on the workspace)
APP=$(curl -fsS -X POST https://api.auth.productcraft.co/v1/apps \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{\"slug\":\"acme-staging\",\"display_name\":\"Acme (staging)\",\"workspace_id\":\"$WS_ID\"}")

APP_ID=$(echo "$APP" | jq -r .id)

# 2. Mint an hdk_live_* API key for the running service
APP_KEY=$(curl -fsS -X POST https://api.auth.productcraft.co/v1/apps/$APP_ID/api-keys \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"staging-service","permissions":["user.read","user.list"]}')

echo "$APP_KEY" | jq -r .key > /etc/secrets/auth-api-key

Both endpoints accept an optional Idempotency-Key header — set one in CI so a retried job doesn't create a duplicate app or a second key whose plaintext nobody saw.

The same workspace API key works against every backend that respects workspace-scoped policy — Auth-admin, Mail, Waitlist, Social, Trawl. Each service introspects the bearer against the Platform API server-side and enforces the key's bound policy. You don't need a separate token per service.

Step 5

Tighten the policy

The default examples above grant broad scopes for brevity. In production, narrow each PAT to exactly what the pipeline needs — see the per-service action list in the API reference.

A few patterns worth copying:

One key per pipeline. Don't reuse a token across a deploy bot and a compliance exporter — the least-privilege blast radius is bigger than it needs to be.
Resource URN narrows. Where the action applies to a per-resource URN (e.g. pcft:heimdall:app/<id>), bind the policy statement to that URN — not *.
Review key activity. Each key's last-used timestamp shows on the API keys page, and administrative actions land in the workspace audit log with the actor recorded. Unused keys are obvious from the activity gap — revoke them.

Browse the full reference

Every endpoint is documented at /docs/platform/api-reference, generated from the live OpenAPI spec. Common starting points: /v1/workspaces, /v1/workspaces/:slug/members, /v1/workspaces/:slug/services, /v1/workspaces/:slug/audit-logs.

For end-user identity in your customer-facing product, you're looking at the wrong page — Auth's docs cover signup, signin, per-app JWKS, tenants, M2M, and the Consumer API for external customers.