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, Heimdall apps, Rally waitlists, members, roles, and audit log.

Your role on the workspace caps what any PAT you mint can do. Owners can mint a PAT with any policy; admins are blocked from destructive verbs like workspace.delete; members can only mint personal-scope tokens.

Step 2

Mint a Personal Access Token

In the console, go to API Keys → Create PAT. Give the token a name (it appears in audit rows), pick a policy, and copy the secret — it's only shown once.

example PAT policy (read-only audit)

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

The token shape is pcft_live_<random>. Treat it like a password — store it in your CI secret store, never commit it. Tokens never expire automatically; rotate or revoke them when the use case ends. Every successful PAT call writes an audit row tagged with the PAT id and the caller IP.

Step 3

Verify the token + introspect your policy

The /v1/introspect endpoint echoes the policy bound to your bearer. Use it as a one-call check that the token reaches the right account and carries the actions you expect.

curl

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

A 200 with the policy in the body confirms the token works. A 401 means the token is invalid, revoked, or malformed.

Step 4

Provision a Heimdall app from CI

The canonical CI/CD use case: your deploy pipeline needs a Heimdall 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
PAT="${PRODUCTCRAFT_PAT}"
WS="${WORKSPACE_SLUG}"

# 1. Create the Heimdall app
APP=$(curl -fsS -X POST https://api.auth.productcraft.co/v1/workspaces/$WS/apps \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{"slug":"acme-staging","display_name":"Acme (staging)"}')

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

# 2. Mint an API key for the running service
KEY=$(curl -fsS -X POST https://api.heimdall.productcraft.co/v1/apps/$APP_ID/api-keys \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{"name":"staging-service"}')

echo "$KEY" | jq -r .secret > /etc/secrets/heimdall-api-key

The same PAT works against every backend that respects workspace-scoped policy — Heimdall-admin, Envoi (mailbox-api), Rally, Agora-admin. The bearer flows through each service's middleware, which calls /v1/introspect/workspaces/:id on the Platform API to resolve the policy server-side. 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 PAT 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 statement to that URN — not *. The console policy editor surfaces this; the API enforces it.
Audit every PAT. The audit log records the PAT id on every action. Periodically review what each token actually did — unused PATs are obvious from the activity gap.

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/audit-logs.

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