API Reference

Anything you can do in the console is available over a JWT-authenticated REST API on port 8443. Responses follow a consistent envelope, and an interactive Swagger explorer is built in.

Authentication#

Authenticate by posting credentials to api/auth/login. A successful call returns a JWT bearer token with a 15-minute expiry. Send it as Authorization: Bearer <token> on every subsequent request.

# POST api/auth/login
{ "username": "admin", "password": "<your-password>" }

The api/auth/login endpoint authenticates against both the Local user store and a configured LDAP/Active Directory directory — the server selects the provider and returns which one authenticated in the response. Configure directory login and group-to-role mapping under api/settings/ldap; see LDAP / Active Directory Integration. A third provider, Keycloak (OIDC), is handled by a separate set of endpoints (below).

The auth endpoints also expose:

Keycloak SSO (OIDC)#

When OIDC is enabled on the server, Athena supports Keycloak single sign-on. Browser clients use the authorization-code + PKCE flow (login → callback); headless clients such as the PowerShell module use the device-code grant and exchange the resulting Keycloak access token at device-token, which returns the same JWT bearer session as a password login. All OIDC logins are provisioned just-in-time and audited under the Keycloak provider.

For the PowerShell equivalent, see Connect-Athena -Keycloak.

A complete PowerShell round-trip — sign in, capture the token, then call a protected endpoint:

# 1. Sign in (self-signed cert -> -SkipCertificateCheck)
$login = Invoke-RestMethod -Method Post -SkipCertificateCheck `
  -Uri "https://<host>:8443/api/auth/login" `
  -ContentType "application/json" `
  -Body (@{ username = "admin"; password = "<your-password>" } | ConvertTo-Json)

# 2. Pull the bearer token out of the response envelope
$token = $login.data.token

# 3. Call a protected endpoint with the Bearer header
Invoke-RestMethod -SkipCertificateCheck `
  -Uri "https://<host>:8443/api/Agents" `
  -Headers @{ Authorization = "Bearer $token" }

Response shape#

Every endpoint returns the same ApiResponse<T> envelope: a success boolean, a human-readable message string, and a data field carrying the payload.

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJ..."
  }
}

Swagger / OpenAPI#

An interactive OpenAPI explorer is built into the server. Enable it with the Swagger:Enabled setting; it is served at the api-docs route prefix:

https://<host>:8443/api-docs

The explorer is published under the title Athena Deploy Center API and lists every endpoint and model described on this page, so you can try calls directly from the browser.

The raw OpenAPI document is served at /swagger/v1/swagger.json, which you can feed to a client generator.

Not seeing the explorer?#

If https://<host>:8443/api-docs returns nothing (a blank page, a 404, or the SPA instead of the Swagger UI), it is almost always because Swagger is disabled on that server. The explorer is opt-in: when Swagger:Enabled is not set, it defaults to off, and neither the UI nor the JSON spec is registered. Work through these checks:

• Confirm Swagger is enabled. Set Swagger:Enabled to true in the server configuration and restart. This can be provided in appsettings.json ("Swagger": { "Enabled": true }) or via the environment variable Swagger__Enabled=true. A per-environment override (for example an appsettings.Production.json or a container env var that sets it to false) will turn the explorer off even if the default config has it on.
• Use the configured route prefix. The path comes from Swagger:RoutePrefix (default api-docs). If your deployment changed it, browse to https://<host>:8443/<that-prefix> instead. The raw spec stays at /swagger/v1/swagger.json regardless of the UI prefix.
• Use HTTPS on the API port. The API listens on 8443 over HTTPS — make sure you are using https:// and the correct port, not plain HTTP or the web console port.
• Restart after changing the setting. Swagger:Enabled is read at startup, so the server must be restarted for a change to take effect.

Once enabled, the UI loads at the route prefix and the spec at /swagger/v1/swagger.json; use the Authorize button to supply your JWT bearer token before trying calls.

Health#

Health endpoints let a monitoring system or script watch the server. The liveness paths answer anonymously with the overall status only; the detail paths return a per-component breakdown (database, certificate authority, audit trail, disk space). See Server Health & Monitoring for the full report, statuses, thresholds, and the Docker healthcheck.

Endpoint groups#

The API is organized into endpoint groups, each rooted at a base route: