Authentication
Header
Send Authorization: Bearer <token>.
Token classification
sk_...-> API key- JWT-shaped token -> access token
- anything else -> invalid token (
AUTH_INVALID_TOKEN)
Classification is handled by extractBearerToken(...) and classifyToken(...) in saas-ai-api/src/lib/authToken.ts.
Public auth modes
Public routes use one of these modes:
access_token_onlyapi_key_or_access_token
api_key_only exists on legacy or non-public routes and is not part of the current public docs surface.
Organization scoping
Current public routes require organizationId.
- Read routes usually take it in the query string
- Write and run routes usually take it in the request body
If organizationId is missing, the resolver returns 400 bad_request.
For API keys, an org mismatch returns AUTH_ORG_MISMATCH.
Public route summary
| Family | Auth mode | User permission | API-key scope |
|---|---|---|---|
GET /api/agents, GET /api/agents/:id, GET /api/agents/:id/versions/:versionId/diff | api_key_or_access_token | ai.use | agents:read |
POST /api/agents, PATCH /api/agents/:id, POST /api/agents/:id/versions, POST /api/agents/:id/publish, PUT /api/agent-versions/:id/workflow, POST /api/agent-versions/:id/workflow/validate, POST /api/agents/:id/versions/:versionId/rollback | api_key_or_access_token | ai.use | agents:write |
POST /api/agents/:id/run | access_token_only | ai.use | not supported |
GET /api/agent-runs/compare, GET /api/agent-runs/:id, POST /api/agent-runs/:id/load-inputs | api_key_or_access_token | ai.use | runs:read |
POST /api/agent-runs/:id/rerun-from-step | access_token_only | ai.use | not supported |
POST /api/setup/verify | api_key_or_access_token | ai.use | runs:read |
| Skill read routes plus preview/diff | api_key_or_access_token | ai.use | skills:read |
| Skill write/version/publish routes | api_key_or_access_token | ai.use | skills:write |
POST /api/skills/:id/run | access_token_only | ai.use | not supported |
| Tool read routes plus diff | api_key_or_access_token | ai.use | tools:read |
| Tool write/version routes | api_key_or_access_token | ai.use | tools:write |
| Evaluation read routes | api_key_or_access_token | ai.use | evaluations:read |
| Evaluation create/run routes | api_key_or_access_token | ai.use | evaluations:write |
Error shape
Auth failures use structured diagnostic fields such as code, title, category, why, and optional recovery.