Authentication

Protected API endpoints require a Bearer token and the x-workspace-id header. You can use either a session token (from login) or an API token (created in Settings → API keys).

Quick reference

Use Authorization: Bearer <token> and x-workspace-id: <workspaceId> on every workspace-scoped request. Optional: send x-correlation-id for request tracing.

Required headers

Header	Required	Description
Authorization	Yes	Bearer <token> — session JWT or API token.
x-workspace-id	Yes (for workspace-scoped and current)	The workspace ID. Must match a workspace the token is allowed to access.
x-correlation-id	No	Request correlation ID for support and logging. If omitted, the server may generate one.
Content-Type	For body	application/json for JSON request bodies.

How to get a session token

Call POST /v1/auth/session with a JSON body.

Email/password (local):

{
  "provider": "local",
  "email": "you@example.com",
  "password": "your-password",
  "workspaceId": "optional-workspace-id"
}

OAuth (Google or Microsoft):

{
  "provider": "google",
  "idToken": "<id-token-from-oauth-client>",
  "workspaceId": "optional-workspace-id"
}

Use "provider": "microsoft" for Microsoft. The idToken is the OAuth ID token from the provider; the API verifies it with the provider’s JWKS.

Response (200): includes accessToken (JWT) and usually user and workspace. Use accessToken as the Bearer token.

API tokens

• Create tokens in the web app: Settings → API keys. Copy the token once at creation; it cannot be retrieved again.
• Use it as the Bearer token: Authorization: Bearer <api-token>.
• API tokens are workspace-scoped: send the same workspace ID in x-workspace-id that the token was created for.

Unauthenticated endpoints

These do not require Authorization or x-workspace-id:

• GET /health
• POST /v1/auth/session
• POST /v1/auth/register
• POST /v1/auth/accept-invite
• POST /v1/auth/verify-email
• POST /v1/auth/resend-verification
• Webhook endpoints (/v1/webhooks/...) — they use their own verification (signature/secret).

All other v1 endpoints require a valid Bearer token and, where applicable, x-workspace-id.

See Auth endpoints for request/response details of session, register, and verify.