Overview
Backend Auth API (1.0.0)
Section titled “Backend Auth API (1.0.0)”Identity, sessions, JWT (RS256), JWKS, password reset, and internal admin APIs.
Response envelope (JSON): most routes return { "success": true, "data": ... } or
{ "success": false, "error": { "code": string, "message": string } }. Exceptions:
GET /.well-known/jwks.json returns raw JWKS JSON (no envelope).
Internal user routes (/internal/users*, /internal/companies/{companyId}/*) require a valid Bearer
access token. Authorization is enforced server-side: platform roles (PLATFORM_ADMIN, PLATFORM_MODERATOR,
PLATFORM_SUPERADMIN) and company roles via company_memberships (see operation descriptions).
Machine routes (/internal/sessions/*, /internal/users/*/revoke-all, /internal/companies/resolve,
/internal/users/*/context) are mounted only when INTERNAL_API_KEY is set at startup; they require
header X-Internal-API-Key. If the env is unset, those paths are not registered (404).
Public registration: POST /auth/register is enabled only when PUBLIC_REGISTRATION_ENABLED=true.
New users get approvalStatus: PENDING until a platform moderator/admin or company admin sets APPROVED
(and typically isActive: true) via PATCH /internal/users/{id} when permitted by RBAC.
- OpenAPI version: 3.0.3
Authentication
Section titled “ Authentication ”bearerAuth
Section titled “bearerAuth ”RS256 access token (Authorization: Bearer
Security scheme type: http
Bearer format: JWT
internalApiKey
Section titled “internalApiKey ”Security scheme type: apiKey
Header parameter name: X-Internal-API-Key