The Platform API uses JSON Web Tokens (JWT) for operator authentication. This is the credential the console uses on behalf of a signed-in operator, and the same credential you use when calling the API from your own scripts or integrations.
It is not the same credential agents use. Agents authenticate to the proxy with a tenant-scoped API key. Operators authenticate to the API with a JWT. Two surfaces, two credential types.
How tokens are issued
Two flows are supported:
1. OTP (one-time password) flow
For tenants without SSO. The operator signs in with email; the API emails an OTP; the operator submits the OTP and receives a short-lived JWT plus a longer-lived refresh token.
2. SAML / OIDC (single sign-on)
For tenants with an identity provider (Okta, Azure AD, Google Workspace, etc.). The operator is redirected to the IdP, comes back with an assertion, and the API exchanges the assertion for the same JWT/refresh-token pair.
Token lifetimes
- Access JWT: short-lived (15 minutes by default). Carried in
Authorization: Bearer …on every API call. - Refresh token: long-lived (30 days by default), used to mint new access JWTs without re-prompting the operator. Refresh tokens are bound to the originating client.
Both lifetimes are tenant-configurable.
Claims
The JWT includes:
sub: operator user ID.tenant_id: the tenant the token is scoped to.roles: the operator’s roles (e.g.admin,member).permissions: fine-grained permissions resolved from the role assignment.exp/iat: standard expiry and issued-at claims.jti: unique token ID, recorded in the audit log on use.
Revocation
Refresh tokens can be revoked from the console (per-session or all sessions for an operator). Access JWTs are short-lived and not individually revocable; if you need an immediate cut-off, revoke the refresh token and the access token expires within minutes.
Operator vs agent credentials
| Operator JWT | Agent API key | |
|---|---|---|
| Used against | Platform API | Proxy |
| Issued by | OTP / SSO flow | Console (per-agent) |
| Lifetime | Minutes (refreshable) | Until manually revoked |
| Identifies | A human operator | A registered agent |
| Scope | A tenant | A single agent |
Never use an agent API key against the Platform API, and never put a JWT in agent code. The two surfaces enforce this separation.
Where to go next
- API overview
- API concepts
- Request access: for the full endpoint reference.