Health endpoints reference

Kāore anō tēnei ihirangi kia wātea i tō reo.

This reference lists the health and status endpoints this release serves, who may reach them, what they return and which subsystems each one probes. This reference reflects Onetime Secret v0.26.19 (e98a88c9).

Reading the tables

Access states the route’s own authentication attribute and any network restriction applied before it. Codes lists the status codes the source sets. Probes separates an endpoint that reports a constant from one that tests a dependency.

Two of these endpoints report a constant: a 200 from them means the process answered a request, not that its dependencies are reachable. Only the advanced endpoint and the auth endpoint test anything, and each reports the result in a field rather than in the status code.

Network restriction

/health and everything under it is restricted before the route runs. The restriction matches the normalized mount-relative path, so it covers every mounted application’s health route, including the auth application’s /auth/health.

Property	Behaviour
Trusted addresses	Loopback and private ranges: RFC 1918, IPv4 and IPv6 loopback, `fc00::/7` and `fe80::/10`.
Extra ranges	`HEALTH_TRUSTED_CIDR` takes a comma-separated list of ranges to add. An invalid entry is logged and skipped.
Denial	403 with a JSON error body, plus a warning log recording the address, path and method.
Sessions	The shipped session skip list keeps `/health`, `/health/advanced`, `/auth/health` and the three API status paths from minting a session. An operator-defined list replaces the shipped one rather than adding to it.

The API status paths are not covered by the network restriction.

Health endpoints

Path	Method	Access	Codes	Probes
`/health`	GET	Route is anonymous; the network restriction still applies.	200; 403 from an untrusted address.	None. The `status` field is the constant `ok`. Payload: `status`, `timestamp`, `version`.
`/health/advanced`	GET	Route is anonymous; the network restriction still applies.	200 for both `ok` and `degraded`, because the handler sets no status; 403 from an untrusted address.	Datastore ping, broker connection with 5-second timeouts, auth database connection test, and the boot-time secret-verifier state. Payload: `status`, `timestamp`, `version` and a `checks` object per subsystem with password-masked URLs. A check reporting `not_configured` is left out of the overall status, which is `ok` only when every remaining check is `ok`.
`/auth/health`	GET	Served only while the auth application is mounted, which is Full mode; the network restriction applies because the path arrives mount-relative.	200; 503 when the handler raises; 403 from an untrusted address; 404 when the auth application is not mounted.	The Rodauth database connection, when one is configured. Payload: `status`, `timestamp`, `database` (`ok`, `error` or `not_required`), `version`, `mode`. The top-level `status` stays `ok` even when `database` reports `error`, so read the `database` field.

API status endpoints

Path	Method	Access	Codes	Probes
`/api/v1/status`	GET	Anonymous callers allowed; basic credentials are validated when supplied.	200; 401 for invalid supplied credentials; 404 when authentication is disabled.	None. Payload: `status` (the constant `nominal`) and `locale`.
`/api/v1/authcheck`	GET	Basic credentials required.	200 for valid credentials; 401 otherwise; 404 when authentication is disabled.	None; it reports whether the supplied credentials authenticate. Payload: `status`, `locale`.
`/api/v2/status`	GET	Public. The route declares no authentication attribute, and the route file states that status stays public because it discloses no build information.	200.	None. Payload: `success`, `status` (the constant `nominal`), `locale`.
`/api/v3/status`	GET	Public, on the same grounds as v2.	200.	None. Payload: `status` (the constant `nominal`), `locale`.
`/api/v2/version`	GET	Authenticated by session or basic credentials. The route file states the build version is withheld from anonymous callers because it fingerprints the install.	200 for an authenticated caller; the failure codes are not determined from source.	None. Payload: `success`, `version` (an array of components), `locale`.
`/api/v3/version`	GET	Authenticated by session or basic credentials, on the same grounds as v2.	200 for an authenticated caller; the failure codes are not determined from source.	None. Payload: `version` (an array of components), `locale`.

See also