Health and Session Endpoints

Flux exposes two lightweight endpoints for runtime diagnostics and principal introspection. /api/health requires no authentication and is safe to call from infrastructure probes. /api/session also requires no authentication — it always returns the caller’s current identity and data-currency state, making it the authoritative source for both unauthenticated login redirects and authenticated shell state.

GET /api/health

Returns the runtime status of the Flux API, its analytical store, and the operational back-end. No authentication is required — this endpoint is designed to be called by load-balancer health probes and uptime monitors. Authentication: None

Response fields

Field	Type	Description
`status`	string	Always `"ok"` when the process is serving.
`service`	string	Always `"flux-api"`.
`version`	string	FastAPI application version (e.g. `"2.0.0"`).
`database`	string	Analytical store engine — always `"duckdb"`.
`operationalDatabase`	string	Control-plane back-end (`"postgresql"`, `"duckdb"`, or empty if disabled).
`authMode`	string	Active authentication mode (`"mock"`, `"entra"`, or `"none"`).
`analyticsReadMode`	string	Whether the instance reads from the live mutable store or a published snapshot (`"direct"` or `"snapshot"`).
`analyticsSnapshotVersion`	string \| null	Present only when `analyticsReadMode` is `"snapshot"`. The version token of the currently-loaded snapshot, or `null` if no snapshot has been adopted yet.

Example

curl https://your-flux-host/api/health

{
  "status": "ok",
  "service": "flux-api",
  "version": "2.0.0",
  "database": "duckdb",
  "operationalDatabase": "postgresql",
  "authMode": "entra",
  "analyticsReadMode": "snapshot",
  "analyticsSnapshotVersion": "20240610T0412Z"
}

GET /api/session

Returns the caller’s identity and the data-currency provenance block used by the shell. The endpoint always responds — it does not enforce authentication — making it safe to call before login to check whether the user is signed in. Authenticated callers receive a full identity payload; unauthenticated callers receive the same response shape with user set to null. Authentication: None — returns the caller’s current authentication state regardless of session validity.

Response fields

The response is a flat object. The identity fields are provided by App Service Authentication (X-MS-CLIENT-PRINCIPAL) and are mapped by Flux’s AuthService.

Field	Type	Description
`authenticated`	boolean	`true` when a valid principal was resolved; `false` for unauthenticated requests.
`authMode`	string	Active authentication mode (`"mock"`, `"entra"`, or `"none"`).
`user`	object \| null	`null` when unauthenticated. Present when authenticated.
`user.id`	string	Object ID of the authenticated user.
`user.displayName`	string	Display name from Entra ID.
`user.email`	string	Principal email address, if available from the claims payload.
`user.roles`	string[]	Flux roles assigned to the principal, e.g. `["reader"]` or `["reader", "admin"]`.
`permissions.canRead`	boolean	`true` when the principal holds the `reader` or `admin` role.
`permissions.canManageIntegrations`	boolean	`true` when the principal holds the `admin` role.
`dataCurrency.mode`	string	Matches `analyticsReadMode` from `/api/health`: `"direct"` or `"snapshot"`.
`dataCurrency.snapshotVersion`	string \| null	Version token of the snapshot this instance is currently serving. Present only in snapshot mode.
`dataCurrency.latestVersion`	string \| null	Version token of the most-recently approved snapshot, read from the operational store. May differ from `snapshotVersion` if a newer snapshot has been approved but not yet adopted.
`dataCurrency.generatedAt`	string \| null	ISO 8601 timestamp at which the latest snapshot was generated.

dataCurrency is read from the operational store on a best-effort basis. If the operational store is unreachable the dataCurrency block will contain only mode and all other fields will be absent — the session response itself will still return 200.

Example

{
  "authenticated": true,
  "authMode": "entra",
  "user": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "displayName": "Alice Nguyen",
    "email": "alice@contoso.com",
    "roles": ["reader", "admin"]
  },
  "permissions": {
    "canRead": true,
    "canManageIntegrations": true,
    "canSyncIntegrations": true
  },
  "dataCurrency": {
    "mode": "snapshot",
    "snapshotVersion": "20240610T0412Z",
    "latestVersion": "20240610T0412Z",
    "generatedAt": "2024-06-10T04:12:00Z"
  }
}

Error responses

Both endpoints return standard FastAPI error shapes. If the analytical store is busy during a long-running writer operation, reads will receive:

{
  "detail": "The analytical database is temporarily busy while a synchronization write completes. Retry shortly.",
  "waitedSeconds": 4.2
}

The HTTP status is 503 Service Unavailable with a Retry-After: 15 header.

​GET /api/health

​Response fields

​Example

​GET /api/session

​Response fields

​Example

​Error responses

GET /api/health

Response fields

Example

GET /api/session

Response fields

Example

Error responses