JSON Web Tokens (JWT)

AgentOS reads the JWT from the Authorization: Bearer <token> header on protected requests. The default public routes are /, /health, /info, /docs, /redoc, /openapi.json, and /docs/oauth2-redirect. Tokens can come from the AgentOS control plane or your own backend.

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)	Array of permission scopes. A missing or malformed claim is treated as no permissions, not a validation error.
`sub`	No	User ID (extracted as `user_id`)
`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.

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/agents

JWTs 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

Get Started

AgentOS

Example Usage

JSON Web Tokens (JWT)

Token Structure

Example Tokens

Sending Tokens

Next Steps

​Token Structure

​Example Tokens

​Sending Tokens

​Next Steps

Token Structure

Example Tokens

Sending Tokens

Next Steps