Skip to main content
ThreatLab’s API uses two authentication mechanisms: session cookies for browser-initiated requests, and a shared Bearer token for the automated noise dispatch endpoint. Understanding which mechanism applies to your caller saves you from unexpected 401 and 403 responses. Session cookies are the standard authentication path for the ThreatLab web UI and any browser-based caller. Used by: the ThreatLab web UI and any browser-based caller. How it works: sign in at /login. Once authenticated, the browser automatically attaches the session cookie to every subsequent request. You do not need to set any header manually in browser environments.

​
Required Capabilities per Route

Not every authenticated user can reach every endpoint. ThreatLab’s capability-based authorization model gates destructive routes behind named capabilities.
RouteRequired Capability
POST /api/sessions/startmanage_exercises
DELETE /api/sessionsmanage_exercises
POST /api/noise/runmanage_noise_logs
GET /api/platform-status/eventsAny authenticated user
Your effective capability set is the union of all permission-role permissions arrays assigned to your account. Contact your ThreatLab administrator if you receive a 403 on a route you expect to access.
Unauthenticated requests receive 401. Authenticated requests that lack the required capability receive 403.

​
Bearer Token Authentication

Bearer token authentication is reserved exclusively for POST /api/noise/run — the automated noise dispatch endpoint invoked by pg_cron or external scripts. Used by: pg_cron scheduled jobs and automation scripts calling POST /api/noise/run only. How to pass the token: 
POST /api/noise/run HTTP/1.1
Host: threatlab.your-org.com
Authorization: Bearer your-noise-dispatch-token
Content-Type: application/json
The token is configured by your administrator on the server. Contact your administrator to obtain the value for your environment.
Bearer token authentication is accepted only on POST /api/noise/run. Passing a Bearer token to any other endpoint will result in a 401 — those routes require a valid session cookie.

​
Unauthenticated Endpoints

GET /api/health requires no authentication and is intentionally open for load balancer probes and uptime monitors. You can call it without any credentials.
Never include your Bearer token or session cookie in URL query parameters. Use the Authorization header for Bearer tokens, or rely on automatic browser cookie handling for session-based requests.