Authorization

JWT validation and scope-based permissions for AgentOS endpoints.

AgentOS validates the JWT on every request, then checks its scopes against the permissions each endpoint requires. This controls who can access and run your agents, teams, and workflows.

Enable authorization when initializing AgentOS:

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS


agent = Agent(
    id="my-agent",
    model=OpenAIResponses(id="gpt-5.2"),
)

agent_os = AgentOS(
    id="my-agent-os",
    agents=[agent],
    authorization=True,
)

app = agent_os.get_app()

Key Concepts

Concept	Description
Tokens	JWTs signed by the control plane or your own backend, sent as Authorization: Bearer <token>
Scopes	Permission strings in the scopes claim, like agents:read or agents:my-agent:run
Roles	Named bundles of scopes assigned to users (Owner, Administrator, Member, or custom)
Isolation	Per-user data scoping for sessions, memories, and traces
Service accounts	Opaque agno_pat_ tokens for machine callers, with scopes stored in your database

Learn How To

Quickstart

Enable authorization, set a verification key, and make your first authenticated request.

JSON Web Tokens (JWT)

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

Self-Hosted (BYO Token)

Run AgentOS without the control plane by issuing and verifying your own JWTs.

Scopes

Scope format and the full permission reference for every AgentOS endpoint.

Roles

Default roles and custom roles defined in the control plane.

Per-User Data Isolation

Scope sessions, memories, and traces to the caller’s user ID.

Service Accounts

Mint, scope, and revoke opaque machine tokens.

Examples

Basic Authorization (Symmetric)

Enable authorization with a shared-secret JWT (HS256).

Basic Authorization (Asymmetric)

Sign with a private key, verify with the public key (RS256).

Per-Agent Permissions

Grant specific permissions to specific agents.

Per-User Data Isolation

Scope sessions, memory, and traces per user with user_isolation=True.

Developer Resources

JWT Middleware

Configure token sources, claim extraction, and scope checking.

AuthorizationConfig Reference

Configuration options for JWT verification.

JWTMiddleware Reference

Complete JWT middleware class reference.