API keys and roles

All API paths start with /api on the same address as the console. A program authenticates with an API key in the X-API-Key header:

curl https://soc.example.com/api/findings?limit=20 \
  -H "X-API-Key: legit_…"

A key belongs to one tenant and sees only that tenant’s data.

Create a key

An administrator creates keys in Settings → API Keys. The key is shown once, when it is created; copy it then. It starts with legit_, and only its SHA-256 hash is stored.

Every key expires. The longest a key can live is one year from creation, and a later expiry date is shortened to that.

Keys can also be managed through the API, with an ADMIN key or session:

Method	Path	Does
POST	/api/auth/api-keys	Create a key: {"role": "ANALYST", "scopes": ["read", "write"], "expires_at": "2027-01-01T00:00:00Z"}
GET	/api/auth/api-keys	List keys: id, role, scopes, created, last used, expiry. Never the key itself.
DELETE	/api/auth/api-keys/{id}	Revoke a key at once

Creating and revoking a key are both written to the audit log.

A key belongs to the person who made it as well as to the tenant. If that person is suspended or removed, the key stops working, and a person whose role was lowered takes the key down with them. A key cannot create another key. GET /api/auth/api-keys shows who made each key in created_by; keys made before 6 November 2026 have none and keep working until they expire, so replace them.

Roles

A key has one role, and the role sets the ceiling:

Role	Can
VIEWER	Read alerts, events, investigations and reports
ANALYST	Everything a viewer can, plus send events, triage alerts, request response actions and approve another person’s request
ADMIN	Everything an analyst can, plus manage users, keys and agents, and approve commands queued straight to an agent

Scopes

Within its role, a key does only what its scopes allow:

Scope	Needed for
read	GET requests
write	POST, PUT, PATCH and DELETE requests
admin	Any request that needs the ADMIN role. An ADMIN key must have it.

A request the role allows but the scopes do not is refused with 403 and API key scope is not sufficient.

Other ways in

Method	Used by
X-API-Key: legit_…	Scripts and other systems
Authorization: Bearer <JWT>	Sessions that signed in through /api/auth/login
Session cookie	The console in a browser. State-changing requests must also send the X-CSRF-Token header, matching the csrf_token cookie.

Requests with an API key or a bearer token do not need the CSRF header.

Agents use their own keys

The Windows agent does not use an API key from Settings. It receives its own key when it registers with an enrollment token, and that key opens only the agent’s own endpoints. See Enroll a Windows endpoint.