Route Reference¶

This page is the canonical inventory of HTTP methods, paths, authentication requirements, and feature-dependent route availability. Guides link here instead of repeating route tables that could drift.

The canonical server separates versioned application APIs from standardized OAuth2/OIDC endpoints. Browser transport, identity workflows, and operator control-plane APIs are application-owned contracts under /api/v1.

Route Families And Authentication¶

Server support routes are mounted independently from the optional application and protocol surfaces:

Liveness returns {"status":"ok"} without consulting SQLite. Readiness reads the database's Alembic revision and compares it with every head shipped in the current checkout. It returns the same success payload when they match, or 503 {"status":"not_ready"} without exposing connection or migration details.

Every /api/v1 operation documents the shared 503 DATABASE_BUSY response. SQLite permits one writer at a time; when the configured busy timeout cannot resolve contention, clients receive Retry-After: 1 and may retry the complete request. OAuth2 protocol routes translate the same condition through their OAuth2 error contract instead of the application error envelope.

With the local Compose HTTPS origin, prefix those paths with https://auth.zero-auth-lite.localhost:8443.

Startup Route Matrix¶

This table is the canonical reference for settings-driven route composition. Other guides link here instead of restating the mounting rules.

identity_workflow.registration_enabled=false removes registration and the ability to request another self-registration verification message. It is required when browser sessions are disabled. JSON confirmation stays mounted so a token issued before the setting changed can still be consumed when api.interactive_auth_routes_enabled=true. Built-in HTML confirmation pages are selected independently by ui.identity_workflow_mode. Organization, server, self-service, health, and enabled OAuth2/OIDC protocol routes are not selected by the JSON or presentation settings.

Management Browser Interfaces¶

The management interfaces are HTML adapters over the same actor-bound services used by the versioned APIs. They accept browser sessions only; Bearer tokens continue to call /api/v1/me, /api/v1/organization, and /api/v1/server directly.

Self-service HTML routes:

The account route is mounted whenever browser sessions are enabled. It does not require an organization-admin or operator role. Email replacement creates a pending address and preserves the current address until verification succeeds.

Organization-administrator HTML routes:

Server-operator HTML routes:

Every page reloads role authority from current identity state. A user who loses the organization-admin or operator role cannot keep using a page through an old session. State-changing forms require the session-bound CSRF token and an accepted Origin. Destructive actions require an explicit confirmation field.

htmx 4 is served from /static/vendor/ and replaces list fragments without moving authorization into the browser. Ordinary links and forms remain usable without JavaScript and successful mutations follow POST/Redirect/GET. Raw OAuth2 client secrets appear only in the immediate no-store creation or rotation response and cannot be retrieved afterward.

The shared Content Security Policy permits htmx connections only to the current origin with connect-src 'self'. Browser-route failures are HTML responses; JSON APIs and OAuth2/OIDC protocol routes retain their own error contracts.

Browser Sessions¶

When api.interactive_auth_routes_enabled=true and sessions are enabled, the following JSON session routes are mounted.

Successful session transport responses use 204 No Content and communicate through cookies plus any configured CSRF header or cookie. Login clients must call GET /api/v1/sessions/csrf first, preserve the returned cookie, and echo the exposed value in the configured header with an accepted Origin. The login JSON body contains the user's email and password.

JSON Identity Workflow Transport¶

The following JSON routes are mounted only when api.interactive_auth_routes_enabled=true.

These are versioned server contracts rather than OAuth2 protocol endpoints. They are mounted as part of the canonical identity lifecycle. The registration and /email/verify/request routes are absent when identity_workflow.registration_enabled is false. /email/verify/confirm remains available for already-issued tokens.

External OAuth2 Interaction Transport¶

These routes are mounted only with ui.oauth2_interaction=external, api.interactive_auth_routes_enabled=true, sessions, and the corresponding interactive grant:

The GET routes require a session. POST additionally requires session-bound CSRF and an accepted origin. All responses are no-store; invalid, expired, consumed, and foreign identifiers share OAUTH2_INTERACTION_INVALID.

Built-In Authentication Transport¶

The startup route matrix is the source of truth for route mounting. The server mounts the no-JavaScript, form-urlencoded identity workflow routes when ui.identity_workflow_mode=builtin; the shared landing, login, and logout routes have the combined conditions stated below.

The GET requests render CSRF-protected forms. The single-use workflow token authorizes the identity change, while the form token and origin check prevent cross-site submission. Successful POST requests use 303 See Other so browser refreshes repeat a GET rather than replaying a credential or token mutation. Mounted UI routes are included in OpenAPI. Authentication forms use the Built-in Authentication UI tag; consent and device pages remain grouped with their corresponding OAuth2 flows. Authentication UI templates use native HTML forms and do not load HTMX. In contrast, /management/account, /management/organization, and /management/operator use the shared management shell, which loads HTMX for progressive enhancement while keeping ordinary links and forms usable without JavaScript.

OAuth2 interaction pages are presentation routes rather than protocol endpoints:

Self-Service And Organization Administration¶

The current-user browser-session list accepts active_only (default true), offset (default 0), and limit (default 50, maximum 100). It returns items, offset, limit, and total, including the matching total before pagination. Sessions are ordered by most recent activity, then by session ID.

The current-user and organization OAuth2-session list routes accept offset and limit. They return items, the applied offset and limit, and total, the number of records matching the filters before pagination. On both routes, each item uses id for its UUIDv4 session identifier and scopes for the array of granted scope strings. The organization route is not a session history: revoked families are deleted and never returned. With active_only=false, it additionally returns expired families whose current token-pair row has not yet been removed by cleanup.

The server derives the organization from the authenticated principal. User update payloads cannot select organization_id, grant operator status, or set a plaintext password.

Password change, self-deletion, and browser-session management are mounted only when browser sessions are enabled. Password change and self-deletion accept the session cookie only and require CSRF protection; a Bearer token carrying profile:write can update ordinary profile fields but cannot change credentials or delete the identity.

Current-user OAuth2 session inspection and revocation are browser-session-only and are mounted when browser sessions and at least one OAuth2 grant are enabled. Revoking an OAuth2 session deletes its stored token state; it does not delete the client registration or the user's identity.

Every /api/v1/organization read operation requires organization:read, and every state change requires organization:write. These scopes cover only the current-organization administration surface. The authenticated user must also hold the organization-admin role; possessing a organization:* scope or the operator role alone does not grant organization-admin authority.

The organization OAuth2 session routes derive the same boundary from that explicit organization-admin principal. Revocation ends the OAuth2 session and removes its stored token family, so those tokens can no longer be used or refreshed. These revocation responses report the affected rows as revoked_sessions and revoked_token_states; one token-state row is not necessarily a token pair. These /api/v1/organization/oauth2 session routes are mounted only when at least one OAuth2 grant is enabled. JWKS publication alone does not mount token-session administration.

Server Control Plane Administration¶

OAuth2 client-administration routes in this section are mounted only when at least one OAuth2 grant is enabled. The remaining server-administration routes belong to the permanent identity baseline.

Client creation accepts user_organization_access and user_organization_ids together, while machine access starts at none. The general client PUT replaces registry fields only and preserves both organization policies. Each dedicated organization endpoint replaces its mode and assignments atomically. Client names are trimmed and must contain at least one visible character. User and machine assignment payloads accept at most 100 distinct organization identifiers.

User-backed organization access has these cardinality rules:

The server rejects a mode and assignment set that does not satisfy these rules; it never persists a partially configured single or selected policy.

Operator privileges are global and distinct from organization-admin privileges. The operator-authorized routes in the server API use resource-specific organizations:*, users:*, sessions:write, and oauth2_clients:* scopes.

Replacing a client policy revokes all of that client's OAuth2 sessions when the replacement removes a scope, grant, active status, organization-access mode, or organization assignment. Capability additions leave existing sessions intact and do not expand the scopes already recorded in their tokens. Machine-organization assignments are current policy rather than token claims, so an existing machine token with sessions:write can use a newly assigned organization immediately.

Organization session revocation is the one explicit-organization control-plane operation that also accepts an OAuth2 client-credentials principal. The client must carry sessions:write; authorization reloads its current machine policy and assignment after authentication. A 404 deliberately does not reveal whether an organization is missing or merely outside a machine client's assignments. Revocation marks browser sessions unusable, ends OAuth2 sessions, and removes their token states. Sessions belonging to other organizations and organizationless machine sessions are not affected.

Successful responses from the authenticated /api/v1/me, /api/v1/organization, and /api/v1/server surfaces carry Cache-Control: no-store and Pragma: no-cache. This includes cookie-authenticated reads, whose requests do not carry an HTTP Authorization header that would otherwise constrain shared caches.

OAuth2 And OpenID Connect¶

Protocol paths below include their canonical /oauth2 prefix.

Discovery uses issuer-derived paths. For the default root-style issuer:

If the issuer contains a path, the discovery paths follow the OAuth2 and OIDC well-known URI rules described in OAuth2 discovery.

There is no OAuth2 master switch. The authorization and device routers are mounted only for their grants, and token/revocation/introspection routes exist only when at least one grant is enabled. A JWKS-only configuration exposes metadata plus /oauth2/jwks.json without token endpoints or application-owned OAuth2 administration routes. OIDC discovery and UserInfo are mounted only when OIDC is enabled.

Use the generated OpenAPI document as the detailed request and response schema reference. OAuth2 routes intentionally preserve typed query, form, header, cookie, and security parameters.

GET /consent and both device-verification methods are built-in HTML routes, not OAuth2 protocol endpoints. When mounted, they remain visible in OpenAPI so the active browser topology can be inspected by tag. /oauth2/authorize remains the protocol entry point. After validation, it redirects to the configured login destination and then, when required, to /consent; the browser carries only an opaque persisted transaction identifier.