API Authentication

Everything the dashboard does, it does over the same public API on your instance. A script calls it with a personal API token; a browser uses a session cookie.

Personal API Tokens (For Scripts)

For anything unattended, create a personal API token and send it as Authorization: Bearer zx_…. A token carries only the permissions you tick when creating it, never more than you hold, and expires (90 days by default, one year at most). Each token is limited to 300 requests per minute. A token cannot call routes that need a sudo step-up or the administrator role, the sign-in, MFA and password routes, or token management itself. Steps: Create an API token.

Your instance also serves an OpenAPI 3.1 reference, a saved file built from the product’s route definitions and shipped with the release it runs, at https://<your-instance>.zonitix.com/api/docs. It covers the areas published for token use (users, groups, roles, workflows and runs, device reads, audit logs, API tokens), not every module — see the API Reference for what each list covers.

What Ends A Token

In plain words: a token belongs to one person’s account and stops when that account stops, when that person’s password changes, or when the token is revoked or runs out. Plan for that before you leave a script running unattended.

The token and its owner are checked on every request, in the order below. The first row that applies refuses the request with 401; the reply carries auth: false and the text shown as message.

• The password row. The account records the moment its sessions were last ended, and a token created before that moment is refused and shown as Invalidated in the token list. Four things set that moment: the owner changes their own password, an administrator sets a new password for them, an administrator expires their password, or they accept an invitation and set a password. A token created afterwards is not affected. The message names a “sign-out-everywhere”, but there is no separate action of that name; the full list is under What Ends A Session Early below.
• Losing a permission does not end the token. On each request the token carries the permissions ticked for it that its owner still holds. A permission taken from the owner stops working for the token within 15 seconds, and the routes that need it answer 403; the rest of the token keeps working. If the permission is given back, the token has it again.
• A lapsed licence does not end a token. Nothing in the token check reads the licence. Routes of a module that is paused refuse a token as they refuse a session; see What Happens When A Subscription Lapses.
• Each refusal is audited. The audit action is API_TOKEN_REJECTED, with the reason from the table, the token’s name and the first characters of the token. A script that keeps retrying a dead token adds one entry per reason every 10 minutes, not one per request.
• A token always has an owner. Every token is tied to one user account; no token exists apart from an account, and there is no client-credentials grant. For an integration that must keep running, use an account kept for that purpose, with MFA set up where your policy requires it, and replace the token before its expiry date and after each change of that account’s password.

Session Sign-In Flow

Post your credentials to the login endpoint. On success the gateway sets a session cookie; the same session token can be sent as Authorization: Bearer <token> instead. This is the flow to use for anything that needs a step-up, which a personal API token cannot do. If the account has MFA enrolled or has not yet accepted terms, the response is a challenge rather than a session. The worked example below takes the second-factor challenge through to a step-up.

Worked Example: Sign In, Second Factor, Step-Up

The script signs in with a password and an authenticator code, shows a step-up-gated call being refused, steps up, and makes the call again. The gated call is the read-only diagnostics download, so running the script changes no setting; it does write audit entries. It needs curl and jq, and an account that signs in with a Zonitix password, has an authenticator app enrolled and holds manage_security.

# Set ZX_USER, ZX_PASSWORD and ZX_CODE (the current 6-digit code from your authenticator app) first.
API='https://<your-instance>-api.zonitix.com'
APP='https://<your-instance>.zonitix.com'

# 1. Password. 200 with a challenge when a second factor is due.
MFA_TOKEN=$(jq -n --arg u "$ZX_USER" --arg p "$ZX_PASSWORD" '{username:$u,password:$p}' \
  | curl -s -X POST "$API/api/v1/auth/login" \
      -H 'Content-Type: application/json' -c cookies.txt -d @- \
  | jq -r .mfaToken)

# 2. Second factor. 200 sets the session cookie.
jq -n --arg m "$MFA_TOKEN" --arg c "$ZX_CODE" '{mfaToken:$m,token:$c}' \
  | curl -s -X POST "$API/api/v1/auth/mfa/verify" \
      -H 'Content-Type: application/json' -c cookies.txt -d @- -o /dev/null -w '%{http_code}\n'

# 3. A step-up-gated call before the step-up. Prints 401; the body's "error" is SUDO_REQUIRED.
curl -s -b cookies.txt -o /dev/null -w '%{http_code}\n' \
  "$API/api/v1/user-management/support/diagnostics"

# 4. Step-up. A POST authenticated by the cookie must carry Origin. 200 replaces the session cookie.
jq -n --arg p "$ZX_PASSWORD" '{password:$p}' \
  | curl -s -X POST "$API/api/v1/auth/sudo" \
      -H 'Content-Type: application/json' -H "Origin: $APP" \
      -b cookies.txt -c cookies.txt -d @- -o /dev/null -w '%{http_code}\n'

# 5. The same call again. Prints 200 and saves the file.
curl -s -b cookies.txt -o diagnostics.json -w '%{http_code}\n' \
  "$API/api/v1/user-management/support/diagnostics"

• Step 1 can answer differently. When no second factor is due, the reply is auth: true with a token and the cookie is already set: skip step 2. The reply can also be a challenge this example does not cover: a second factor that still has to be set up (mfaStatus: "setup_pending"), terms that have not been accepted, or a password that must be changed.
• The interim token is short-lived. mfaToken lasts 5 minutes and is refused as a session. The limits on wrong codes are on MFA Enforcement.
• Origin, or a bearer. Only step 4 needs Origin in this script: it is the one request that changes something and is authenticated by the cookie alone. Its value is the app address, not the API address. To do without it, read token from the step 2 reply and send Authorization: Bearer <token> on the later requests; after step 4, use the new token from that reply, because the older one carries no step-up.
• The refusal on other routes. A missing or expired step-up is refused with "error": "SUDO_REQUIRED" in the response body. The status beside it is 400 on most routes, because the gateway turns a 401 from a service behind it into 400. It stays 401 on the routes the gateway passes through unchanged: removing a passkey, the diagnostics bundle, and in Security Lab starting an aggressive scan, changing a scan scope and archiving findings. Key on the error string, not the status.

Session Tokens

A session token is a JWT signed with HS256 using a secret held on your instance. Its lifetime is the Absolute Timeout an administrator sets under Security Settings → Sessions (the sessionTimeout setting): 8 hours on a new instance, and any value from 5 minutes to 24 hours. Activity does not extend it. Signing in again, or completing a step-up, issues a new token.

• In production the cookie is named __Host-token and is set HttpOnly, Secure, SameSite=None, Path=/ with no Domain, so it is bound to your instance’s API address. Its max-age is the time the token has left, capped at 24 hours.
• The interim token returned by a sign-in that still needs a second factor or a forced password change lasts 5 minutes and is refused as a session.
• The server re-reads the account on every request, so disabling a user or expiring their password ends their sessions at once, whatever the token’s own expiry says. Every case is in the table under What ends a session early, below.
• Changing the timeout affects tokens issued after the change; tokens already issued keep their original expiry.

What Ends A Session Early

A session token is not stored on the server, so it cannot be deleted. It is cut short in one of two ways: that one token is listed as signed out, or the account records a moment (sessionsInvalidatedAt) and every token issued before it is refused with 401 and the message Session expired — please sign in again.

• There is no separate “sign out everywhere” action. To end every session of one person, change or reset their password, or disable the account.
• There is no refresh token. POST /api/v1/auth/refresh exchanges a session token that is still valid for a new one with a fresh expiry. It refuses a signed-out token, a blocked account and a token issued before the account’s invalidation moment. The token that was exchanged is not signed out by the exchange; it stays usable until its own expiry.
• Personal API tokens follow the same moment. A token created before the owner’s sessions were last invalidated stops working and is shown as Invalidated in the token list. A blocked owner’s tokens stop on the next request. Every case, with the message each one returns, is under What Ends A Token above; the steps are in Create an API token.
• Where the signed-out list is kept. In Redis, each entry expiring when the token itself would. If Redis cannot be reached at that moment the entry is kept in the identity service’s own memory instead, and both places are checked on every request. An entry held only in memory is lost if that service restarts before the token expires.

Token Claims

The token is signed and not encrypted, so anyone who holds it can read these claims. It is a bearer credential: sent in the Authorization header it is worth exactly what the cookie is worth. Every place that verifies it accepts HS256 only. There is no iss, aud or jti claim.

The roles and permissions in the token are a snapshot. The gateway does not authorise from them: it asks the identity service to validate the token and re-read the account, and forwards that answer to the service doing the work (see Transport & Service Trust). The gateway reuses an answer for the same token for at most one second. How passwords are hashed and when an account locks are on the same page.

Cookie Sessions And CSRF

A request that changes something (any method other than GET, HEAD or OPTIONS) and is authenticated by the session cookie alone must carry an Origin header (or, failing that, a Referer) naming your instance’s app address (https://<your-instance>.zonitix.com, not the API address). Without one the gateway answers 403 with CSRF check failed: missing or untrusted Origin. and records the attempt in the audit log. A request that carries an Authorization header is not subject to this check, so a script that uses a personal API token never meets it. The one exception is the SAML assertion endpoint, POST /api/v1/auth/sso/saml/acs, which your identity provider posts to from its own origin.

Path Conventions