Authentication

All OMN REST APIs are secured with OAuth 2.0 / OpenID Connect JSON Web Tokens (JWT), issued by the Keycloak server that ships with OMN. Every API request must carry a valid token in the Authorization header:

Authorization: Bearer <TOKEN>

If the API also enforces authorization, the related permission information is carried inside the same token — tokens inherit the exact permissions of the user they were issued for. To inspect and debug a JWT, use jwt.io.

OpenID Connect discovery

Keycloak is a standard OAuth 2.0 / OIDC server. Every OMN installation exposes its OIDC configuration at the well-known URL:

https://<OMN_SERVER>/auth/realms/OMN/.well-known/openid-configuration

OMN uses the Authorization Code flow to authenticate users and authorize API access — the most secure option recommended by OIDC. To spare you the browser-based implementation effort, OMN provides a Token Management feature in the OMN UI (User Settings → Tokens) where users can generate both token types directly. Other standard OAuth 2.0 flows work with Keycloak but are not officially supported; only the Authorization Code flow is fully tested with OMN’s permission logic.

Token types

Both token types are issued by Keycloak for the omn-ui client:

  • Access token — used directly in the Authorization header. Expires after a set period (currently one hour) and is bound to the user session: logging out of OMN invalidates it immediately. Recommended for testing and short-term API access only.

  • Offline token — a special refresh token that cannot call the API directly but is exchanged for fresh access tokens. It is not bound to an active session, survives logout, and is the right choice for backend services and production integrations. It expires after 30 days of non-use; each refresh extends it by a new 30-day lifespan.

Using an access token

curl --location --request GET 'https://<OMN_SERVER>/api/v1/search/omn-search-version' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Obtaining tokens programmatically

The recommended way to obtain tokens is through the OMN UI (User Settings → Tokens, based on the Authorization Code flow). Where no UI interaction is possible, the Resource Owner Password Credentials (ROPC) flow can obtain an offline token directly:

curl --location --request POST 'https://<OMN_SERVER>/auth/realms/OMN/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=omn-ui' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=YOUR_USER_NAME' \
--data-urlencode 'password=YOUR_USER_PASSWORD' \
--data-urlencode 'scope=openid offline_access'
The ROPC flow handles the user’s password directly. Use it only in trusted environments; prefer the Authorization Code flow (or the OMN UI token management) wherever possible.

Offline tokens in production

Exchange the offline token for a new access token (and a rotated offline token):

curl --location --request POST 'https://<OMN_SERVER>/auth/realms/OMN/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=omn-ui' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=OFFLINE_TOKEN' \
--data-urlencode 'scope=openid offline_access'

Key characteristics:

  • The returned access token has the same lifespan as one obtained from the OMN UI and can be used directly for API calls.

  • The offline session refreshes with a new 30-day lifespan on every exchange.

  • With the Keycloak option Revoke refresh tokens disabled (the default), the previous offline token remains valid after the exchange; when enabled, it becomes invalid and must be replaced with the newly returned one.

Recommendations for production clients:

  • Implement token rotation for both access and offline tokens — rotation logic is the responsibility of the client application. Always replace the stored offline token with the newly returned one, regardless of the Revoke refresh tokens setting.

  • Reuse access tokens for as long as they are valid instead of requesting a new one per call — requesting tokens for every request puts unnecessary load on the server.

  • Prefer an established OAuth/Keycloak client library for the rotation logic over a hand-rolled implementation.

Keycloak 18 contains a bug that may cause incorrect behavior of offline sessions. Verify in the omn-ui client that the advanced settings Client Session Idle and Client Session Max are left empty.