Scopes

Scopes are permission strings carried by the caller's credential: the JWT scopes claim, or the stored scopes of a service account token. Protected operations with insufficient scopes usually return 403 Forbidden. Agent, team, and workflow listings can instead return a filtered or empty list. Unmapped custom routes have no automatic scope requirement.

Scope Format

Scopes are hierarchical:

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.

The agent_os:admin scope grants full access to every AgentOS endpoint below.

AgentOS Control Plane Scopes

AgentOS Scopes

Run polling, history, and checkpoint reads require both scopes shown above: middleware checks the resource's read permission and the run handler checks its run permission. Equivalent per-resource grants can target a specific component. A default service-account token has run permissions but lacks agent, team, and workflow read permissions, so add the relevant read grant before polling protected REST run endpoints.

AG-UI's POST /agui route requires a global or wildcard run grant for its target family, such as agents:run or agents:*:run, or the corresponding team grants. A specific-agent or specific-team grant does not pass this route's scope check. Custom AG-UI prefixes use the same family requirement.

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.

Direct API calls need the scopes of their own operations; config:read is not a prerequisite for every endpoint.

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.

An empty scope list removes the permission requirement for that mapping but does not bypass authentication. Unmapped custom REST handlers and arbitrary MCP callable tools need an explicit policy if access requires finer permissions. Built-in MCP tools retain their native scope mappings even when you customize REST mappings.

Next Steps