API reference
The server publishes a machine-readable API document and a documentation UI
under the versioned prefix when [server.docs] enabled = true (public only
with public = true; otherwise an authenticated session is required).
Auth column shorthand:
- public — no authentication.
- client — OAuth2 client authentication (client credentials at the token endpoint, or the client’s own identity in the flow).
- admin — an administrative session or an API key with the matching area-and-right grant (the deny-by-default access matrix).
- platform — the
platform_adminrole (platform administration only). - tenant — the platform administrator or an administrator of exactly this tenant.
Operations and diagnostics
Section titled “Operations and diagnostics”| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/auth/v1/ping |
public | Liveness probe. |
GET |
/auth/v1/ready |
public | Readiness probe. |
GET |
/auth/v1/health |
public | Subsystem health. |
GET |
/auth/v1/version |
public | Running version. |
GET |
/auth/v1/whoami |
public | Reverse-proxy diagnostic (headers echoed only with whoami_headers). |
Events and email
Section titled “Events and email”| Method | Path | Auth | Purpose |
|---|---|---|---|
POST |
/auth/v1/events |
admin | Query event records. |
GET |
/auth/v1/events/stream |
admin | Live event stream (SSE). |
POST |
/auth/v1/events/test |
admin | Trigger a test event (full admin only). |
GET |
/auth/v1/email |
admin | List bulk email jobs. |
POST |
/auth/v1/email |
admin | Create a bulk email job. |
POST |
/auth/v1/email/cancel/{id} |
admin | Cancel a bulk email job. |
An API key needs the events grant: read to query events and follow the
stream, create to start a bulk email job, update to cancel one. Group
administrators can read events but not send mail; only a full administrator
can trigger a test event. On a tenant’s own path the query answers that
tenant’s events. The stream, the test event and bulk email belong to the
deployment itself and do not exist on a tenant’s path.
Rotating the signing keys (/auth/v1/oidc/rotate_jwk) needs a full
administrator or an API key with the secrets grant’s update right. The
API documentation, when it is not public, needs a signed-in session or an API
key.
Clients
Section titled “Clients”| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/auth/v1/clients |
admin | List clients. |
POST |
/auth/v1/clients |
admin | Create a client. |
GET |
/auth/v1/clients/{id} |
admin | Read a client. |
PUT |
/auth/v1/clients/{id} |
admin | Replace a client. |
DELETE |
/auth/v1/clients/{id} |
admin | Delete a client. |
POST |
/auth/v1/clients/{id}/secret |
admin | Read a client secret. |
PUT |
/auth/v1/clients/{id}/secret |
admin | Rotate a client secret. |
Only a full administrator of the tenant (or the platform administrator) or an
API key of that tenant may use these routes. A key needs the clients grant
with the matching right (read, create, update, delete); reading or rotating a
secret needs the secrets grant (read or update) instead. Any other caller is
refused, including an administrator of another tenant.
Dynamic client registration (RFC 7591-style) is governed by
[clients] dynamic_registration_enabled; while off, every dynamic
registration endpoint answers not-found and discovery omits the registration
endpoint. A client registers in the tenant whose address it uses
(/auth/v1/<tenant>/clients_dyn) and belongs to that tenant only.
OIDC protocol
Section titled “OIDC protocol”| Method | Path | Auth | Purpose |
|---|---|---|---|
GET/POST |
/auth/v1/oidc/authorize |
public/client | Authorization entry point / credential submission step. |
POST |
/auth/v1/oidc/authorize/refresh |
session | Silent re-authentication. |
POST |
/auth/v1/oidc/session |
public | Session bootstrap. |
GET |
/auth/v1/oidc/sessioninfo |
session | Session document. |
GET |
/auth/v1/oidc/sessioninfo/xsrf |
session | Session CSRF token re-issue. |
POST |
/auth/v1/oidc/token |
client | Token issuance. |
POST |
/auth/v1/oidc/introspect |
client | Token introspection. |
POST |
/auth/v1/oidc/token/revoke |
client | Token revocation. |
GET/POST |
/auth/v1/oidc/userinfo |
token | Userinfo document. |
GET/POST |
/auth/v1/oidc/forward_auth |
token | Forward-authentication headers. |
GET |
/auth/v1/oidc/certs |
public | Published key set. |
GET |
/auth/v1/oidc/certs/{kid} |
public | Published key by id. |
POST |
/auth/v1/oidc/rotate_jwk |
admin | Rotate the signing keys. |
POST |
/auth/v1/oidc/device |
client | Device authorization start. |
POST |
/auth/v1/oidc/device/verify |
session | Device authorization decision. |
GET/POST |
/auth/v1/oidc/logout |
public/session | End-session page / confirmation and backchannel-logout receiver. |
POST |
/auth/v1/pow |
public | Fetch a proof-of-work challenge. |
Discovery is served at the issuer’s own address
(/auth/v1/.well-known/openid-configuration) and at the host root (see
Authentication & OIDC).
Users (accounts)
Section titled “Users (accounts)”| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/auth/v1/users |
admin | List accounts. |
POST |
/auth/v1/users |
admin | Create an account. |
GET |
/auth/v1/users/{id} |
admin | Read an account. |
PUT |
/auth/v1/users/{id} |
admin | Replace an account. |
PATCH |
/auth/v1/users/{id} |
admin | Patch an account. |
DELETE |
/auth/v1/users/{id} |
admin | Delete an account. |
GET |
/auth/v1/users/email/{email} |
admin | Look up an account by address. |
GET |
/auth/v1/users/{id}/attr |
admin | Read an account’s attribute values. |
PUT |
/auth/v1/users/{id}/attr |
admin | Update an account’s attribute values. |
GET |
/auth/v1/users/{id}/attr/editable |
admin | Read the user-editable attributes. |
GET |
/auth/v1/users/picture_config |
admin | Read the picture configuration. |
PUT |
/auth/v1/users/{user_id}/picture |
admin | Upload an account picture. |
GET |
/auth/v1/users/{user_id}/picture/{picture_id} |
admin | Fetch an account picture. |
DELETE |
/auth/v1/users/{user_id}/picture/{picture_id} |
admin | Remove an account picture. |
Passkey and device sub-resources of an account are listed under Authentication & OIDC.
Sessions
Section titled “Sessions”| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/auth/v1/sessions |
admin | List sessions. |
DELETE |
/auth/v1/sessions |
admin | Invalidate every session. |
DELETE |
/auth/v1/sessions/{user_id} |
admin | Force logout of one account. |
DELETE |
/auth/v1/sessions/id/{session_id} |
admin | Delete one session. |
Tenants
Section titled “Tenants”| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/auth/v1/tenants |
platform | List tenants. |
POST |
/auth/v1/tenants |
platform | Create a tenant. |
GET |
/auth/v1/tenants/{slug} |
tenant | Read a tenant. |
PUT |
/auth/v1/tenants/{slug} |
tenant | Update a tenant. |
DELETE |
/auth/v1/tenants/{slug} |
platform | Delete a suspended tenant. |
POST |
/auth/v1/tenants/{slug}/suspend |
platform | Suspend a tenant. |
POST |
/auth/v1/tenants/{slug}/activate |
platform | Reactivate a suspended tenant. |
GET |
/auth/v1/tenants/hostnames |
platform | Every tenant hostname, with tenant, kind, state and certificate status. |
GET |
/auth/v1/tenants/{slug}/hostnames |
tenant | One tenant’s hostnames. |
GET |
/auth/v1/tenants/{slug}/hostnames/{host} |
tenant | Read a hostname, with the DNS record a custom one publishes. |
PUT |
/auth/v1/tenants/{slug}/hostnames/{host} |
platform | Add a hostname (an alias; the primary is the tenant’s primary_hostname). |
DELETE |
/auth/v1/tenants/{slug}/hostnames/{host} |
platform | Remove an alias hostname. |
POST |
/auth/v1/tenants/{slug}/hostnames/{host}/verification |
tenant | Check the DNS record now (once a minute), or {"override": "VERIFIED", "reason": "…"} as the platform administrator. |
PUT /auth/v1/tenants/{slug} takes primary_hostname (a hostname, or null
to remove it) and sign_in.email_first (auto or off). Changing the
primary hostname changes the tenant’s issuer, so it is refused with 409
once the tenant has applications other than the console, unless a platform
administrator adds ?force=true. With [tenants] tenant_hostnames = true,
a tenant’s own administrators may add and remove its aliases and custom
hostnames.
A tenant slug cannot be one of the reserved segments, because the route
would hide the tenant: every first-level segment of /auth/v1 (such as
oidc, users or tenants), plus sign-in (the shared sign-in page),
sign_in_domains and hostnames. The full list is in
Tenants & multitenancy.
See Tenants & multitenancy for the model and lifecycle rules.
Console support
Section titled “Console support”The console-support endpoints (/auth/v1/console/access,
/auth/v1/console/providers, /auth/v1/console/users/search,
/auth/v1/console/sessions/search, and the /auth/v1/blacklist surface)
are listed in the console guide.
Roles, groups, scopes, API keys
Section titled “Roles, groups, scopes, API keys”The privilege registries (roles, groups, scopes) and API keys carry their
own admin surface under /auth/v1/roles, /auth/v1/groups,
/auth/v1/scopes, and /auth/v1/api_keys, mounted per tenant, plus the
policy reads under /auth/v1/password_policy, /auth/v1/login_time, and
/auth/v1/password_hash_times. These routes are part of the versioned tree
(their segments are reserved against tenant slugs) but are not registered in
the OpenAPI document table above.