Resources · Authentication

Authentication & Scope Documentation

Production-ready guide for JWT/session auth, API key auth, scope headers, workspace context, and validation rules.

Authentication Methods

JWT/session authentication for user-context requests.
API key authentication for service-to-service and controlled integrations.

Required Headers

Authorization: Bearer [jwt_token] OR X-API-Key: [api_key]Content-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: required only in workspace scope

Scope Model

Personal scope executes under the authenticated user context.
Workspace scope executes under a specific workspace with role-aware controls.

Validation Rules

If scope is personal, X-Workspace-ID must not be provided.
If scope is workspace, X-Workspace-ID is required.
Invalid or conflicting scope headers return 422.

JWT Authentication Example

bash

curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [jwt_token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Hello from JWT auth",
    "stream":false
  }'

API Key Authentication Example

bash

curl -X POST "/api/v1/chat/completions" \
  -H "X-API-Key: [api_key]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: workspace" \
  -H "X-Workspace-ID: [workspace_uuid]" \
  -d '{
    "message":"Hello from API key auth",
    "stream":false
  }'

Workspace Scope

json

{
  "headers": {
    "X-Scope-Type": "workspace",
    "X-Workspace-ID": "[workspace_uuid]"
  },
  "note": "Workspace scope requires workspace id."
}

Personal Scope

json

{
  "headers": {
    "X-Scope-Type": "personal"
  },
  "note": "Personal scope must not include workspace id."
}

Error Models

401

Authentication missing, expired, or invalid.

403

Scope not allowed or role restriction in workspace.

422

Header/context validation failed.

429

Rate limit exceeded for current auth context.