Auth model overview

Exo authenticates three kinds of caller: people (a User JWT), the Exo Operator (a deployment token), and a small set of service endpoints (per-resource tokens for agent webhooks and SCIM). Each is scoped to a different actor and lifecycle.

Credential types

1Credential          Subject              Where it comes from              Lifetime
2──────────          ────────             ────────────────────             ────────
3User JWT            a person             POST /auth/login | /signup       24h (configurable)
4Deployment token    one Exo Operator     Dashboard → Deployments          indefinite (rotatable)
5Agent webhook       one agent webhook    Dashboard → Agent → Webhooks     indefinite (rotatable)
6SCIM bearer token   one IdP              Dashboard → Identity provider    indefinite (rotatable)

User JWT

Issued to a human after they sign in. Carries the user's identity, tenant, and role/permission set at the moment of login. Used by the dashboard for every request, and by anything scripting against the dashboard's CRUD surface (the exo CLI caches one after exo login).

1curl -X POST https://exo.example.com/api/v1/auth/login \
2  -H "Content-Type: application/json" \
3  -d '{"email":"ada@example.com","password":"…"}'
4# → { "token": "eyJhbGc...", "expires_at": "2026-05-14T17:30:00Z" }

Lifetime defaults to 24 hours; configurable per tenant and signed with EXO_JWT_SECRET (see Config & secrets). There is no refresh-token dance — the user signs in again. SSO sign-in (SAML / OIDC) issues the same JWT at the end of the browser flow.

Deployment tokens

The credential the Exo Operator presents to the control plane. A deployment token (exo_dpl_ + 32 hex) authenticates one Exo Operator instance and carries no per-resource permissions of its own — user authorisation for what happens through a deployment (shell attach, agent invoke) is enforced by the control plane at request time. Full lifecycle in Exo Operator · Tokens; wiring it up in Connecting.

Service tokens

Per-resource tokens that authenticate a single inbound endpoint. Each is minted in the dashboard, shown once, and optionally paired with an HMAC signing secret.

• Agent webhook tokens — gate POST /api/v1/webhooks/agents/:id/invoke. Sent as a Bearer or X-Webhook-Token header, with optional X-Exo-Signature HMAC verification.
• SCIM bearer tokens — minted per identity provider for the SCIM 2.0 server under /api/v1/scim/v2/..., used by your IdP to push users and groups.

Picking the right one

• A person in the dashboard or driving the CLI: User JWT.
• The Exo Operator on a cluster: Deployment token. One per deployment, never shared.
• An external system triggering an agent: an agent webhook token (with HMAC if the caller can sign).
• Your IdP provisioning users: a SCIM bearer token.