REST API

The OpenAPI 3.1 documents in api/ are the source of truth for the REST API, and each service’s tests hold its router to its document: every route is documented, every documented route exists, and every response the tests see matches its schema. The reference pages are generated from those documents on every build:

• User API: sign-in links, the signed-in user, email change and Google sign-in. Source: api/user.openapi.yaml.
• Auth API: sessions, OAuth apps, the OAuth 2 endpoints and the keys that verify every access token. Source: api/auth.openapi.yaml.

Paths

Every route is served through the gateway, under /api/user or /api/auth, which are the documents’ servers. The gateway strips the prefix, so the user service sees /api/user/v1/me as /v1/me. The reference shows the paths as the services see them, and its code samples use https://example.com for your public address.

Authentication

Scheme	In	Used by
bearer	Authorization: Bearer <access token>	Third-party apps and other services, on both APIs
cookie	the access_token cookie	The web app, on both APIs
refreshCookie	the refresh_token cookie	The auth API’s session refresh and sign-out
clientBasic	Authorization: Basic with the client ID and secret	OAuth apps at /oauth/token and /oauth/revoke

Each operation lists the schemes it accepts and the scopes it needs. Authentication explains the tokens, the scopes and the grants.

Errors

Errors are problem details, the Problem schema in both documents. The exceptions are /oauth/token and /oauth/revoke, which answer with the RFC 6749 OAuthError shape, {"error", "error_description"}, because that is what OAuth clients parse.

Probes

Each service answers GET /livez and GET /readyz on its own listener. They are documented with the rest, and described in Observability.