Login & JWT Sessions
OmniWeb authenticates operators with a username and password and issues a JSON Web Token (JWT). That token proves who you are on every subsequent request — and, crucially, it is the same credential that authorises the embedded Grafana, Loki, and Homer. One login spans the whole stack.
← Authentication & Access Control · ← Operations Guide
Login Flow
The token is issued by POST /api/auth/login. Once obtained, the SPA presents it on every API call, and the backend verifies the signature and expiry before doing anything else.
The login screen. Authenticating here yields the JWT that governs the entire stack — element APIs, Loki, Grafana, and Homer.
How the Token Is Carried
The backend accepts the JWT in three locations, which lets the same token work for XHR API calls, browser navigations, and embedded iframes alike:
| Location | Used for |
|---|---|
| Authorization header | Standard API (XHR/fetch) requests from the SPA |
Cookie (access_token, HttpOnly) | Browser navigations and embedded content (Grafana iframe, Homer tab) |
| Query string | Cases where neither a header nor a cookie can be set |
The cookie is HttpOnly (not readable by JavaScript) and uses SameSite=Lax, which protects the token from theft via cross-site script access while still allowing top-level navigations to the embedded tools.
Token Lifetime
The access token has a configurable expiry — 24 hours by default (JWT_ACCESS_TOKEN_EXPIRES, in seconds). When it expires, the operator is returned to the login screen and re-authenticates. There is no silent indefinite session; the lifetime is a deliberate security boundary.
| Setting | Default | Description |
|---|---|---|
JWT_ACCESS_TOKEN_EXPIRES | 86400 (24 h) | Access-token lifetime in seconds. Lower it for tighter sessions; raise it for fewer re-logins. |
JWT_SECRET_KEY | (generated) | Secret used to sign and verify tokens. Set explicitly in production so tokens survive a backend restart and are consistent across instances. |
One Login, Whole Stack
The same JWT authorises the integrated monitoring tools, so operators never log in twice:
- Element APIs and Loki are reached through the backend proxy, which checks the JWT directly.
- Grafana and Homer are reached through the authenticated gateway, which verifies your OmniWeb login before proxying — no second password. See Grafana and Homer.
This is why a single OmniWeb session governs the entire operational surface — dashboards, logs, traces, and element management all ride on the one token.
First Login & Changing Credentials
A fresh deployment ships with a default administrator account (admin / admin). Change this immediately after first login, via Settings. The default exists only to bootstrap the system and must not survive into production.
Logout & Expiry
Logging out discards the token. An expired or invalid token causes the next request to be rejected and the SPA to return to the login screen. Because element actions are only ever performed through an authenticated, RBAC-checked proxy call, an expired session can never perform a privileged action.
Related
- Role-Based Access Control — what a logged-in user is allowed to do.
- Audit Logging — every authenticated action is recorded.