Skip to main content
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. JWT verification flow 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

ConceptDescription
TokensJWTs signed by the control plane or your own backend, sent as Authorization: Bearer <token>
ScopesPermission strings in the scopes claim, like agents:read or agents:my-agent:run
RolesNamed bundles of scopes assigned to users (Owner, Administrator, Member, or custom)
IsolationPer-user data scoping for sessions, memories, and traces

​
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.

Customization

Override scope mappings to add custom endpoints or change defaults.

​
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.