HTTP endpoints

Every HTTP route the server mounts, apart from the admin API (/admin/...), which has its own reference. Paths are relative to PUBLIC_URL; examples use https://id.example.com and the tenant acme, whose issuer is https://id.example.com/t/acme.

Tenant endpoints live under /t/{slug}. A tenant with a custom domain also answers every one of them on its own host without the prefix (https://login.acme.example/token as well as https://id.example.com/t/acme/token); both forms report the same issuer. A custom host serves that tenant only: besides the tenant’s routes it answers /healthz, /readyz, /.well-known/webfinger, /.well-known/security.txt and the tenant’s own /t/{slug}/… and /scim/v2/{slug}/… paths, and 404 for everything else (the admin API, /metrics, /docs, /openapi.json, other tenants). The router lives in api/src/lib.rs.

The Limit column names the rate-limit family a route counts against (see Rate limits, IP rules and CAPTCHA). Tenant IP rules are checked by the same guard, so routes marked — are subject to neither.

Global

The container image’s HEALTHCHECK runs ridm-api --healthcheck inside the container, which probes /healthz at BIND_ADDR (loopback for a wildcard address), over HTTPS when TLS_CERT is set.

Tenant OpenID Connect and OAuth 2.0

Client authentication

/token, /par, /device_authorization, /bc-authorize, /introspect and /revoke authenticate the client with the method registered for it; any other method is invalid_client. A client under the FAPI 2.0 profile must use private_key_jwt with the issuer as the assertion’s aud.

| tls_client_auth | client_id in the body, over a mutual-TLS connection with a certificate from one of the tenant’s trusted authorities that carries the client’s registered subject (Mutual TLS) | | self_signed_tls_client_auth | client_id in the body, over a mutual-TLS connection with a certificate registered in the client’s jwks or jwks_uri (x5c) |

The two mutual-TLS methods are offered when the deployment can receive client certificates (MTLS_BIND or CLIENT_CERT_HEADER); discovery then lists them, tls_client_certificate_bound_access_tokens: true and, with MTLS_PUBLIC_URL, the mtls_endpoint_aliases where they are used. client_secret_jwt is not implemented.

Grant types at /token

A client may only use the grants in its allowed_grants; a known grant it is not allowed is unauthorized_client, an unknown one unsupported_grant_type. Audiences come from resource parameters (RFC 8707; token exchange also takes audience), or from the client’s allowed_audiences when none is requested, plus the resource server of any requested scope bound to one; see Resource servers, scopes and permissions and Token claims.

The response is {"access_token", "token_type", "expires_in", "refresh_token"?, "id_token"?, "scope"?, "issued_token_type"?} with Cache-Control: no-store. token_type is DPoP when a DPoP proof bound the tokens, otherwise Bearer (a certificate-bound token is a Bearer token, checked against the connection’s certificate).

Discovery document

The discovery document advertises exactly what the build implements (api/src/oidc/discovery.rs). Endpoints are {issuer}/authorize, /token, /.well-known/jwks.json, /userinfo, /introspect, /revoke, /end_session, /par, /device_authorization and /bc-authorize (backchannel_authentication_endpoint); registration_endpoint ({issuer}/register) appears only when the tenant’s dcr.mode is not disabled.

form_post is not offered as a plain response mode, only as form_post.jwt. Userinfo responses are plain JSON, so userinfo_signing_alg_values_supported is absent. Server-provided DPoP nonces and dpop_jkt at /authorize are not implemented.

Browser flow API

The sign-in pages drive a login flow through these routes. A flow is created by /authorize (or by device verification) and identified by {id}. Every mutating step carries the flow’s csrf token in its JSON body; a wrong one is 403. Responses carry the public flow state; when its stage is done the page navigates to finish_url. All are in the flows limit family and answer errors as RFC 9457 problems (see Errors). The flow is described in Sign-in flows and sessions.

Registration, invitations, recovery, verification and devices

All in the flows limit family; errors are problem documents.

SAML identity provider

Every tenant is a SAML 2.0 IdP whose entity ID is its issuer. See SAML identity provider.

Identity brokering

Register the callback URL with the upstream provider; the admin API reports it as callback_url on every identity provider (for SAML, the assertion consumer service, with the rest under saml_sp). See Identity brokering.

Account API

The self-service API for a signed-in user, under /t/{slug}/account. It takes a bearer (or DPoP-bound) access token, JWT or opaque, issued by that tenant with the urn:ridm:account audience (the built-in ridm-account-console client obtains one), or a personal access token with the account scope. It acts only on the token’s own subject. Errors are RFC 9457 problems; security changes may answer 403 with type urn:ridm:error:reauthentication-required (see Errors). These routes are in the OpenAPI document under the account tag and are not rate limited by the guard.

A few behaviours the table leaves out:

• Password change. PUT password needs the current password while one is set; sign_out_others: true ends every other session, with back-channel logout.
• Contact changes. A six-digit code goes to the new address (or number); the right code moves the account over, verified, and the previous address is told. An address another account uses is a 409. Codes are hashed and single-use, good for ten minutes and five attempts, with three sends per ten minutes; a repeat inside twenty seconds reuses the pending code. The phone number cannot be removed while it backs an SMS second step (400).
• Linking. The browser returns from the broker to the account console with ?linked=1 or ?link_error=<code>.
• Personal access tokens. GET tokens also lists the scopes a new token may carry (account, plus the admin permissions the user holds) and the tenant’s maximum lifetime.
• Export and deletion. The export holds the record, credential metadata, devices, sessions, consents, roles, groups and the audit trail, never secret material. DELETE me needs the username typed again as confirmation; see deletion for what follows.

Request and response bodies are in the rendered reference.

SCIM 2.0

A SCIM service provider per tenant at /scim/v2/{slug} (RFC 7643, RFC 7644). Every request needs Authorization: Bearer rscim_..., a provisioning token minted for that tenant (see SCIM provisioning). Bodies are application/scim+json; errors are SCIM error documents (Errors). Not rate limited by the guard.

Headers on every response

A security-headers layer adds the browser hardening headers (and Strict-Transport-Security when PUBLIC_URL is https and HSTS_MAX_AGE is not 0); CORS is answered for the UI’s and the API’s own origins and for each client’s registered cors_origins. Rate-limited families add RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.