Skip to main content
Scopes are permission strings in the JWT scopes claim. Each AgentOS endpoint requires one or more scopes; requests with insufficient scopes return 403 Forbidden.

​
Scope Format

Scopes are hierarchical:
FormatExampleDescription
resource:actionagents:readAccess all resources of a type
resource:<id>:actionagents:my-agent:runAccess a specific resource
resource:*:actionagents:*:readWildcard (equivalent to global)
agent_os:admin-Full access to all endpoints

​
Scope Reference

Scopes are enforced at two layers. Control plane scopes are enforced by the AgentOS control plane at os.agno.com. AgentOS scopes are enforced by your deployed AgentOS service on every API request. Any agents:action, teams:action, or workflows:action scope also accepts a resource:<id>:action form to limit access to a specific resource. For example, agents:web-agent:run grants run access only to the web-agent. Use * as the id (agents:*:run) to match every resource of that type. See Scope Format.
Per-resource scoping applies to agents, teams, and workflows only. All other resource types (sessions, memories, knowledge, traces, etc.) use global scopes only. The resource:<id>:action form is not honored for them.
The agent_os:admin scope grants full access to every AgentOS endpoint below.

​
AgentOS Control Plane Scopes

ScopeDescription
os:readView AgentOS instances in the organization
os:writeCreate and update AgentOS instances
os:deleteDelete AgentOS instances
org:readView organization details
org:writeUpdate organization details
org:deleteDelete the organization
org:members:readView organization members
org:members:writeInvite and update organization members
org:roles:readView organization roles and their scope assignments
org:roles:writeCreate and update organization role scopes
org:roles:deleteDelete organization roles
billing:readView billing details and invoices
billing:writeUpdate billing settings and payment methods

​
AgentOS Scopes

ScopeEndpointDescription
config:readGET /configRead the OS configuration
config:readGET /modelsList available models
config:writePOST /databases/all/migrateRun migrations on all databases
config:writePOST /databases/*/migrateRun migrations on a specific database

​
Access Prerequisites

A few scopes gate access in the control plane. Without them, finer-grained scopes have no effect because the user cannot reach the resources they apply to.
ScopeWithout it, the user cannot
org:readAccess the organization at all
os:readList AgentOS instances in the organization
config:readUse any AgentOS endpoint (the UI loads /config on startup)

​
Custom Scope Mappings

Customize or extend the default scope mappings using the JWT middleware: 
from agno.os import AgentOS
from agno.os.middleware import JWTMiddleware

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

app = agent_os.get_app()

app.add_middleware(
    JWTMiddleware,
    verification_keys=["your-jwt-key"],
    algorithm="RS256",
    authorization=True,
    scope_mappings={
        "POST /custom/endpoint": ["custom:write"],  # custom route: full freedom
        "GET /custom/data": ["custom:read"],        # custom route: full freedom
        "GET /public/stats": [],                    # no scopes required
    }
)
Custom scope mappings are additive to the defaults. To override a default, specify the same route pattern with your custom scopes.
Built-in routes preserve their native resource namespace. Handlers for /agents, /teams, and /workflows re-check scopes against their native namespace (agents:, teams:, workflows:). Mapping GET /agents to custom:read won’t grant access because the handler still requires agents:read. Full freedom applies only to new routes you define yourself.

​
Next Steps

TaskGuide
Bundle scopes into rolesRoles
Configure JWT middleware in depthJWT Middleware