Authentication

Workshop supports three practical auth paths:

Path Best for Header
API key principal Servers, operators, automation x-api-key: sk_...
Short-lived bearer token Browsers, MCP clients, delegated sessions Authorization: Bearer ...
Same-origin demo auth Hosted demo Studio only no header from the browser

For protected /api/* routes, org scope is resolved from the authenticated principal or signed bearer token. Do not rely on caller-supplied x-org-id for tenant isolation. Older SDKs may still send it for compatibility, but the server-side auth context is authoritative.

API Key Auth

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

API keys may be provided from two backends:

  • Environment-configured keys through WS_API_KEYS for simple deployments.
  • Postgres-backed API principals in the api_principals table for managed deployments.

Postgres principals store a hash of the API key, not the plaintext secret. The plaintext key is returned only once when the principal is created.

Bearer Token Auth

Bearer tokens are signed Workshop session tokens. They are useful when a server wants to mint a short-lived credential for a browser, agent, or connector.

bash
curl -X POST "$WORKSHOP_URL/api/session-token" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WORKSHOP_API_KEY" \
  -d '{ "ttlSeconds": 3600, "scopes": ["render:write"] }'
json
{
  "tokenType": "Bearer",
  "accessToken": "eyJ...",
  "orgId": "org_demo",
  "principalId": "prn_...",
  "scopes": ["render:write"],
  "issuedAt": "2026-07-09T00:00:00.000Z",
  "expiresAt": "2026-07-09T01:00:00.000Z"
}

Use the token like this:

bash
curl "$WORKSHOP_URL/api/mcp/tools" \
  -H "Authorization: Bearer $WORKSHOP_BEARER_TOKEN"

Managing API Principals

Principals require Postgres persistence. They are scoped to the current authenticated org.

Route Purpose
GET /api/principals List principals for the current org
POST /api/principals Create a new API principal and return its one-time key
DELETE /api/principals/{id} Disable a principal

See Principals and Tokens for examples.

OAuth For Remote MCP

Remote MCP clients can discover Workshop's OAuth metadata:

Route Purpose
GET /.well-known/oauth-protected-resource Protected resource metadata
GET /.well-known/oauth-protected-resource/api/mcp Resource metadata for MCP
GET /.well-known/oauth-authorization-server Authorization server metadata
POST /oauth/token Client-credentials token endpoint

Workshop supports OAuth client credentials for remote MCP connectors. Interactive user OAuth onboarding is a separate workflow.

Demo Mode

The hosted demo Studio may call protected routes without sending a key when same-origin demo auth is enabled and the request origin is allowlisted. This is intended for the browser demo surface, not server-to-server integrations.

Common Failures

Status Meaning Fix
401 Missing or invalid credential Send a valid x-api-key or bearer token
403 Authenticated, but method or scope is not allowed Use an API-key principal for principal management, or request narrower token scopes
501 Feature requires unavailable persistence or signing config Enable Postgres persistence or WS_BEARER_SIGNING_SECRET
429 Rate limit exceeded Retry after the rate-limit window

Next Steps