JSON Web Tokens (JWT)

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

⌘I

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