Authentication HTTP API
Use the server URL of your own deployment. Worker examples require a currently valid bearer token; provider callbacks use native signatures. REPLACE_WITH_RETURNED_ID values refer to IDs obtained through setup or prior operations. Headless setup supplies the credentials and entities.
Check that the engine process is alive
Section titled “Check that the engine process is alive”GET /healthz
Check that the engine process is alive.
Authorization: Public health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.
Result and recovery
Section titled “Result and recovery”{status: "ok"} on success. Readiness returns status unavailable with HTTP 503 when the database cannot be reached.
Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.
Response media type: application/json. | Field | Type | Usage |
| — | — | — |
| status | string | Process/readiness result. |
Check that the engine can serve with its database/schema
Section titled “Check that the engine can serve with its database/schema”GET /readyz
Check that the engine can serve with its database/schema.
Authorization: Public health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.
Result and recovery
Section titled “Result and recovery”{status: "ready"} on success. Readiness returns status unavailable with HTTP 503 when the database cannot be reached.
Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.
Response media type: application/json. | Field | Type | Usage |
| — | — | — |
| status | string | Process/readiness result. |
Retrieve this engine’s public API contract
Section titled “Retrieve this engine’s public API contract”GET /openapi.json
Retrieve this engine’s public API contract.
Authorization: Public health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.
Result and recovery
Section titled “Result and recovery”OpenAPI JSON document.
Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.
Response media type: application/json. object. See the operation-specific result contract.
Discover the login methods configured for this deployment
Section titled “Discover the login methods configured for this deployment”GET /api/v1/auth/methods
Discover the login methods configured for this deployment.
Authorization: Public health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.
Result and recovery
Section titled “Result and recovery”token and oidc booleans describe the configured login methods, without secrets.
Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.
Response media type: application/json. | Field | Type | Usage |
| — | — | — |
| token | boolean | Token login is available. |
| oidc | boolean | Whether OIDC is configured. |
Start the configured OIDC browser login flow
Section titled “Start the configured OIDC browser login flow”GET /auth/oidc/start
Start the configured OIDC browser login flow.
Authorization: Public health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.
Result and recovery
Section titled “Result and recovery”Browser redirect with protected state and nonce cookies.
Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.
Response media type: application/json. object. See the operation-specific result contract.
Complete the configured OIDC login flow
Section titled “Complete the configured OIDC login flow”GET /auth/oidc/callback
Complete the configured OIDC login flow.
Authorization: Public health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.
Result and recovery
Section titled “Result and recovery”Validated browser session and redirect; not a general worker token endpoint.
Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.
Response media type: application/json. object. See the operation-specific result contract.
Create a browser session using the deployment’s enabled login mechanism
Section titled “Create a browser session using the deployment’s enabled login mechanism”POST /api/v1/auth/login
Create a browser session using the deployment’s enabled login mechanism.
Authorization: Public health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
token (required) |
string |
Bearer credential. Save in protected server-side storage and never expose it in browser code or logs. |
Result and recovery
Section titled “Result and recovery”{ok: true} after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.
Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.
Response media type: application/json. | Field | Type | Usage |
| — | — | — |
| ok | boolean | True after the operation succeeds. |
End the current browser session
Section titled “End the current browser session”POST /api/v1/auth/logout
End the current browser session.
Authorization: Public health/discovery or browser authentication flow, as indicated by the operation. Provider callbacks validate their own state.
Content-Type: application/json.
object. See the operation-specific result contract.
Result and recovery
Section titled “Result and recovery”{ok: true} after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.
Readiness may return 503. Login rejects missing/invalid credentials and OIDC state; a redirect is not JSON.
Response media type: application/json. | Field | Type | Usage |
| — | — | — |
| ok | boolean | True after the operation succeeds. |