# Authentication HTTP API

Inputs, results, permissions and errors for the authentication endpoints.

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](https://beepgrid.com/docs/start/headless.md) supplies the credentials and entities.

<a id="get-healthz"></a>

## 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

`{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. |


<a id="get-readyz"></a>

## 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

`{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. |


<a id="get-openapi-json"></a>

## 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

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.


<a id="get-api-v1-auth-methods"></a>

## 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

`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. |


<a id="get-auth-oidc-start"></a>

## 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

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.


<a id="get-auth-oidc-callback"></a>

## 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

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.


<a id="post-api-v1-auth-login"></a>

## 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.


### Input

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

`{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. |


<a id="post-api-v1-auth-logout"></a>

## 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.


### Input

Content-Type: `application/json`.

`object`. See the operation-specific result contract.

### 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. |