JSON Web Tokens (JWT)

JWT claim structure, example tokens, and how AgentOS reads them.

AgentOS reads the JWT from the Authorization: Bearer <token> header on every request. 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	Yes	Array of permission scopes
sub	No	User ID (extracted as user_id)
session_id	No	Session ID for session tracking
aud	No	Audience (must match AgentOS id 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

Next Steps

Task	Guide
Issue tokens from your own backend	Self-Hosted
See the full scope reference	Scopes
Configure JWT middleware directly	JWT Middleware