# Health endpoints reference

> The health and status endpoints this release serves, with their access policy, status codes, payload fields and which subsystems each one actually probes.

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

* [Verify your install](/en/install/verify)
* [Configuration Reference](/en/reference/configuration-files-and-precedence)
* [Upgrade Guides](/en/self-hosting/upgrade-guides)