Authorization
JWT validation and scope-based permissions for AgentOS endpoints.
With authorization=True, AgentOS validates JWTs on protected requests and checks their scopes against endpoint requirements. This controls who can access and run your agents, teams, and workflows. Discovery, self-authenticating webhooks, and MCP OAuth have surface-specific policies.
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 | Opt-in per-user scoping for built-in user-owned data and resources with user_isolation=True |
| 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 user-owned AgentOS data and resources 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 user-owned data and resources throughout AgentOS with user_isolation=True.