JSON Web Tokens (JWT)
JWT claim structure, example tokens, and how AgentOS reads them.
AgentOS reads JWTs from the Authorization: Bearer <token> header on protected requests by default. Tokens can come from the AgentOS control plane or your own backend. JWT middleware can also read cookies.
Token Structure
Your JWT tokens should include:
{
"sub": "user-123",
"scopes": ["agents:read", "agents:my-agent:run"],
"exp": 1735689600,
"iat": 1735603200
}| Claim | Required | Description |
|---|---|---|
scopes | No (needed for RBAC) | Use an array of scope strings. A string becomes one scope; it is not split on spaces. Missing values and values that are neither strings nor lists become an empty list. |
sub | Required for scoped user operations | User ID (extracted as user_id). With user isolation enabled, scoped operations reject a missing or unusable identity with 403. |
session_id | No | Session ID for session tracking |
aud | No | Audience (must match the configured audience, or the AgentOS id by default, when verify_audience=True) |
exp | No | Expiry timestamp. Recommended; expired tokens are rejected. |
iat | No | Issued-at timestamp. |
JWT subjects starting with sa: or __oauth__:, and the exact subject __scheduler__, are reserved for server-assigned identities. AgentOS rejects these subjects even when the JWT signature is valid. The timestamps above illustrate the payload shape; mint fresh expiry values for real tokens.
Example Tokens
Read-only access:
{
"scopes": ["agents:read", "teams:read", "sessions:read"]
}Run a specific agent:
{
"scopes": ["agents:my-agent:run", "agents:my-agent:read", "sessions:write"]
}Admin access:
{
"scopes": ["agent_os:admin"]
}See Scopes for the full list.
Sending Tokens
Send the token in the Authorization header:
curl -H "Authorization: Bearer $TOKEN" http://localhost:7777/agentsJWTs identify human callers. For machine callers, mint a service account token instead. agno tokens create <name> returns an agno_pat_... token that you send in the same Authorization header.
Next Steps
| Task | Guide |
|---|---|
| Issue tokens from your own backend | Self-Hosted |
| Authenticate machine callers | Service Accounts |
| See the full scope reference | Scopes |
| Configure JWT middleware directly | JWT Middleware |