Principals and Tokens

API principals are org-scoped machine identities. They let you create, list, and disable API keys without editing environment variables. This requires Postgres persistence.

List Principals

GET/api/principals

List API principals

Returns API principals for the authenticated org.

bash
curl "$WORKSHOP_URL/api/principals" \
  -H "x-api-key: $WORKSHOP_API_KEY"

Create Principal

POST/api/principals

Create API principal

Creates a new principal and returns the plaintext API key once.

bash
curl -X POST "$WORKSHOP_URL/api/principals" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WORKSHOP_API_KEY" \
  -d '{ "name": "Render Worker", "scopes": ["render:write", "documents:write"] }'
json
{
  "principal": {
    "id": "prn_abc123",
    "orgId": "org_demo",
    "type": "api_key",
    "name": "Render Worker",
    "scopes": ["render:write", "documents:write"],
    "disabled": false,
    "createdAt": "2026-07-09T00:00:00.000Z"
  },
  "apiKey": "sk_live_..."
}

Store the key immediately. The server stores only a hash.

Disable Principal

DELETE/api/principals/{id}

Disable API principal

Disables a principal without deleting audit history.

bash
curl -X DELETE "$WORKSHOP_URL/api/principals/prn_abc123" \
  -H "x-api-key: $WORKSHOP_API_KEY"

Mint Bearer Token

POST/api/session-token

Create short-lived bearer token

Mints a signed bearer token for delegated clients.

bash
curl -X POST "$WORKSHOP_URL/api/session-token" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WORKSHOP_API_KEY" \
  -d '{ "ttlSeconds": 900, "scopes": ["render:write"] }'

Use bearer tokens for browser sessions, remote MCP connectors, and tools that should not receive long-lived API keys.

Requirements

Feature Required config
DB-backed principals Postgres persistence enabled and migrated
Bearer tokens WS_BEARER_SIGNING_SECRET configured
OAuth client credentials DB-backed principal validation and bearer signing

Next Steps