Authentication methods and token lifecycle

The platform exposes three distinct authentication mechanisms, each designed for a different consumer.

Platform docs

Error responses Rate limits Pagination Webhooks Authentication Versioning Idempotency Billing plans Billing flows

Details

Agent Token Auth

Machine-to-machine (Bearer token)

Transport: HTTP Authorization: Bearer {token} header. Accepted credentials: primary workspace API key (format: agk_xxx.yyy) or short-lived access token from POST /api/v1/agent_tokens. Access tokens expire after 2,592,000 seconds (30 days). Credentials carry explicit scopes (e.g., traces:write, gateway:check, agent_commands:read).

Socket tokens

Agents can mint a socket token via POST /api/v1/socket_tokens for WebSocket authentication. Socket tokens expire after 600 seconds (10 minutes).

Details

Session Auth

Operator browser sessions

Transport: session cookie (_agent_ops_key) set after login. Session lifetime: 14 days. Tokens older than 7 days are automatically reissued. Remember me cookie: _agent_ops_web_user_remember_me (14-day max age). Operator sockets use a SHA-256 hash of the session token as the socket ID.

Details

SCIM Token Auth

Enterprise provisioning

Transport: HTTP Authorization: Bearer {scim_token}. Token scope: workspace SCIM bearer token configured in workspace settings. Endpoints: all routes under /scim/v2/*. Content type: application/scim+json. SCIM tokens do not expire; rotate via workspace settings.

Reference

When to use which

Consumer	Auth method	Token source
Service agent (HTTP)	Bearer token or API key	POST /api/v1/agent_tokens or direct API key
Service agent (WebSocket)	Socket token	POST /api/v1/socket_tokens (600s TTL)
Operator (browser)	Session cookie	Login via /users/log-in
Identity provider (SCIM)	SCIM Bearer token	Workspace settings

Related docs

Realtime guide

Socket token minting and WebSocket auth

Authentication endpoints

Token exchange API reference

Idempotency

Credential-aware retry patterns