Authentication

The API authenticates with personal access tokens. A token is tied to one user in one company: API calls made with it act as that user, with exactly that user's permissions — the same ones that apply in the SecurityTrax UI.

Create a token

Requires. API access enabled for your user. If you don't see API Access under Settings, an administrator can grant it from Administration → SecurityTrax API (or with the API access switch on your user's edit page).

In SecurityTrax, open the user menu (your avatar) and click Settings.
Click API Access in the settings navigation.
Under Create a token, fill in the form:

Field	Required?	Type	Notes
Name	Yes	Text	A label so you can recognize the token later — e.g. `My CLI`, `Zapier`.
Expires (optional)	No	Date	Leave empty for a token that never expires; set a date to have it stop working automatically.

Click Generate token. The full token is displayed once, in a Copy your new token dialog. Copy it and store it somewhere safe — after you click Done, SecurityTrax can never show it again (only a hash is stored). If you lose a token, revoke it and create a new one.

Your active tokens are listed on the same page with their name, a token preview, last-used time, creation date, and expiration.

Token format

stx_acme_h2Kb81rQzXeM4tYw0cPnL5sVdA9fGjUoE7iC3mNa

Tokens start with stx_, followed by your company identifier, followed by a random secret. The prefix tells you at a glance which company a token belongs to — and lets secret scanners recognize a leaked SecurityTrax token.

A token only works against its own company's URLs: a token minted in acme is rejected everywhere except /acme/user/v4/....

Use the token

Send it as a bearer token in the Authorization header on every request:

curl "https://portal.securitytrax.com/acme/user/v4/customers" \
  -H "Authorization: Bearer stx_acme_h2Kb81rQzXeM4tYw0cPnL5sVdA9fGjUoE7iC3mNa"

There is no session or login handshake — every request authenticates independently, so clients can hold tokens for several companies at once and use them concurrently.

Authentication failures

Response	Meaning
`401` `unauthenticated`	The token is missing, malformed, revoked, expired, or used against the wrong company URL.
`403` `permission_denied`	The token is valid, but the user is not currently permitted to use the API (for example, the account was deactivated or API access was turned off).

{
  "ok": false,
  "data": null,
  "errors": [
    { "code": "unauthenticated", "status": 401, "detail": "missing bearer token" }
  ]
}

Keep tokens safe

Treat a token like a password. Anyone holding it can act as you.
Never commit tokens to source control or embed them in client-side code. Store them in environment variables or a secrets manager.
One token per application. Name each token after the thing using it, so you can revoke one integration without breaking the others.
Revoke immediately if leaked — Settings → API Access → Revoke. The token stops working on the next request. Revocation cannot be undone.
Prefer an expiration date for tokens used in short-lived or experimental tooling.