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_only
• api_key_or_access_token

api_key_only exists on legacy or non-public routes and is not part of the current public docs surface.

Prompt Orchestra uses route-scoped API keys. The shipped model is not a generic read / write / execute key model.

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 matrix

The canonical public route matrix is generated from the public auth inventory:

• Which Routes Support Which Auth
• API Key Presets

Error shape

Auth failures use structured diagnostic fields such as code, title, category, why, and optional recovery.

See also

• Public Boundary
• Errors
• Bearer Tokens