Scopes

Scope formats and built-in permission mappings for AgentOS routes.

Scopes are permission strings carried by the caller’s credential: the JWT scopes claim, or the stored scopes of a service account token. When authorization is enabled, protected routes compare these scopes with their permission requirements. Requests with insufficient scopes return 403 Forbidden.

Scope Format

Scopes are hierarchical:

Format	Example	Description
resource:action	agents:read	Access all resources of a type
resource:<id>:action	agents:my-agent:run	Access a specific resource
resource:*:action	agents:*:read	Wildcard (equivalent to global)
agent_os:admin	-	Satisfies every required AgentOS scope

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 protected API requests.

The tables below summarize the built-in mappings for public AgentOS routes in Agno 2.7.4. Interfaces, custom routes, and custom prefixes can add mappings. Check /openapi.json on your deployed AgentOS for its active route list.

The agents:read, agents:run, teams:read, teams:run, workflows:read, and workflows:run scopes also accept a resource:<id>:action form. 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 satisfies every required AgentOS scope below.

AgentOS Control Plane Scopes

Scope	Description
os:read	View AgentOS instances in the organization
os:write	Create and update AgentOS instances
os:delete	Delete AgentOS instances
org:read	View organization details
org:write	Update organization details
org:delete	Delete the organization
org:members:read	View organization members
org:members:write	Invite and update organization members
org:roles:read	View organization roles and their scope assignments
org:roles:write	Create and update organization role scopes
org:roles:delete	Delete organization roles
billing:read	View billing details and invoices
billing:write	Update billing settings and payment methods

AgentOS Scopes

Config

Scope	Endpoint	Description
config:read	GET /config	Read the OS configuration
config:read	GET /models	List available models
config:write	POST /databases/all/migrate	Run migrations on all databases
config:write	POST /databases/*/migrate	Run migrations on a specific database

Legacy system:read and system:write scopes are accepted as aliases for config:read and config:write, so tokens issued before the rename keep working. Use config:* in new tokens.

Registry

Scope	Endpoint	Description
registry:read	GET /registry	View the code-defined registry (tools, models, databases)

Components

Studio stores agent, team, and workflow definitions and their config versions through /components. Use these scopes for stored component CRUD. The /agents, /teams, and /workflows routes expose registered resources and run operations.

Scope	Endpoint	Description
components:read	GET /components	List components
components:read	GET /components/*	View a component
components:read	GET /components/*/configs	List a component’s configs
components:read	GET /components/*/configs/*	View a component config
components:read	GET /components/*/configs/current	View the current component config
components:write	POST /components	Create a component
components:write	POST /components/*/configs	Create a component config
components:write	POST /components/*/configs/*/set-current	Mark a config as current
components:write	PATCH /components/*	Update a component
components:write	PATCH /components/*/configs/*	Update a component config
components:delete	DELETE /components/*	Delete a component
components:delete	DELETE /components/*/configs/*	Delete a component config

Agents, Teams, Workflows

These routes discover registered resources and execute them. Stored component CRUD uses /components.

Resource	Scope	Operation	Endpoint pattern
Agents	agents:read	List agents	GET /agents
Agents	agents:read	Get agent details	GET /agents/{agent_id}
Agents	agents:run	Create a run	POST /agents/{agent_id}/runs
Agents	agents:read and agents:run	List or get runs	GET /agents/{agent_id}/runs, GET /agents/{agent_id}/runs/{run_id}
Agents	agents:read and agents:run	List checkpoints or get a checkpoint snapshot	GET /agents/{agent_id}/runs/{run_id}/checkpoints, GET /agents/{agent_id}/runs/{run_id}/checkpoints/{message_index}
Agents	agents:run	Cancel, continue, or resume a run	POST /agents/{agent_id}/runs/{run_id}/cancel, POST /agents/{agent_id}/runs/{run_id}/continue, POST /agents/{agent_id}/runs/{run_id}/resume
Agents	agents:run	Fork a session	POST /agents/{agent_id}/sessions/{session_id}/fork
Teams	teams:read	List teams	GET /teams
Teams	teams:read	Get team details	GET /teams/{team_id}
Teams	teams:run	Create a run	POST /teams/{team_id}/runs
Teams	teams:read and teams:run	List or get runs	GET /teams/{team_id}/runs, GET /teams/{team_id}/runs/{run_id}
Teams	teams:read and teams:run	List checkpoints or get a checkpoint snapshot	GET /teams/{team_id}/runs/{run_id}/checkpoints, GET /teams/{team_id}/runs/{run_id}/checkpoints/{message_index}
Teams	teams:run	Cancel, continue, or resume a run	POST /teams/{team_id}/runs/{run_id}/cancel, POST /teams/{team_id}/runs/{run_id}/continue, POST /teams/{team_id}/runs/{run_id}/resume
Teams	teams:run	Fork a session	POST /teams/{team_id}/sessions/{session_id}/fork
Workflows	workflows:read	List workflows	GET /workflows
Workflows	workflows:read	Get workflow details	GET /workflows/{workflow_id}
Workflows	workflows:run	Create a run	POST /workflows/{workflow_id}/runs
Workflows	workflows:read and workflows:run	List or get runs	GET /workflows/{workflow_id}/runs, GET /workflows/{workflow_id}/runs/{run_id}
Workflows	workflows:run	Cancel, continue, or resume a run	POST /workflows/{workflow_id}/runs/{run_id}/cancel, POST /workflows/{workflow_id}/runs/{run_id}/continue, POST /workflows/{workflow_id}/runs/{run_id}/resume

The nested GET run and checkpoint routes have a :run route dependency. The default GET /agents/*, GET /teams/*, and GET /workflows/* middleware mappings also apply the matching :read scope, so the table lists both requirements for those routes.

Sessions

Scope	Endpoint	Description
sessions:read	GET /sessions	List sessions
sessions:read	GET /sessions/*	View a session
sessions:write	POST /sessions	Create a session
sessions:write	POST /sessions/*/rename	Rename a session
sessions:write	PATCH /sessions/*	Update a session
sessions:delete	DELETE /sessions	Delete sessions in bulk
sessions:delete	DELETE /sessions/*	Delete a session

Memories

Scope	Endpoint	Description
memories:read	GET /memories	List memories
memories:read	GET /memories/*	View a memory
memories:read	GET /memory_topics	List memory topics
memories:read	GET /user_memory_stats	View user memory stats
memories:write	POST /memories	Create a memory
memories:write	PATCH /memories/*	Update a memory
memories:write	POST /optimize-memories	Optimize memories
memories:delete	DELETE /memories	Delete memories in bulk
memories:delete	DELETE /memories/*	Delete a memory

Learnings

Scope	Endpoint	Description
learnings:read	GET /learnings	List learnings
learnings:read	GET /learnings/*	View a learning
learnings:write	POST /learnings	Create a learning
learnings:write	PATCH /learnings/*	Update a learning
learnings:delete	DELETE /learnings/*	Delete a learning

Knowledge

Scope	Endpoint	Description
knowledge:read	GET /knowledge/content	List knowledge content
knowledge:read	GET /knowledge/content/*	View knowledge content
knowledge:read	GET /knowledge/config	View knowledge config
knowledge:read	GET /knowledge/*/sources	List knowledge sources
knowledge:read	GET /knowledge/*/sources/*/files	List files in a source
knowledge:read	POST /knowledge/search	Search knowledge
knowledge:write	POST /knowledge/content	Add knowledge content
knowledge:write	POST /knowledge/remote-content	Add remote knowledge content
knowledge:write	PATCH /knowledge/content/*	Update knowledge content
knowledge:delete	DELETE /knowledge/content	Delete knowledge content in bulk
knowledge:delete	DELETE /knowledge/content/*	Delete knowledge content

Metrics

Scope	Endpoint	Description
metrics:read	GET /metrics	View metrics
metrics:write	POST /metrics/refresh	Refresh metrics

Evals

Scope	Endpoint	Description
evals:read	GET /eval-runs	List eval runs
evals:read	GET /eval-runs/*	View an eval run
evals:write	POST /eval-runs	Create an eval run
evals:write	PATCH /eval-runs/*	Update an eval run
evals:delete	DELETE /eval-runs	Delete eval runs in bulk

Traces

Scope	Endpoint	Description
traces:read	GET /traces	List traces
traces:read	GET /traces/*	View a trace
traces:read	GET /trace_session_stats	View trace session stats
traces:read	POST /traces/search	Search traces

Service Accounts

Scope	Endpoint	Description
service_accounts:read	GET /service-accounts	List service accounts
service_accounts:write	POST /service-accounts	Mint a service account token
service_accounts:delete	DELETE /service-accounts/*	Revoke a service account

All service_accounts scopes are privileged when granted to a token: they let a token mint or revoke tokens.

Schedules

Scope	Endpoint	Description
schedules:read	GET /schedules	List schedules
schedules:read	GET /schedules/*	View a schedule
schedules:read	GET /schedules/*/runs	List schedule runs
schedules:read	GET /schedules/*/runs/*	View a schedule run
schedules:write	POST /schedules	Create a schedule
schedules:write	PATCH /schedules/*	Update a schedule
schedules:write	POST /schedules/*/enable	Enable a schedule
schedules:write	POST /schedules/*/disable	Disable a schedule
schedules:write	POST /schedules/*/trigger	Trigger a schedule
schedules:delete	DELETE /schedules/*	Delete a schedule

Approvals

Scope	Endpoint	Description
approvals:read	GET /approvals	List approval requests
approvals:read	GET /approvals/count	Count approval requests
approvals:read	GET /approvals/*	View an approval request
approvals:read	GET /approvals/*/status	View approval status
approvals:write	POST /approvals/*/resolve	Resolve an approval request
approvals:delete	DELETE /approvals/*	Delete an approval request

Interfaces (A2A)

A2A routes reuse the agents, teams, and workflows scopes. Per-resource scopes like agents:my-agent:run authorize A2A paths the same way they do REST paths. The routes below assume the default /a2a prefix; a custom A2A(prefix=...) is gated the same way under its own prefix.

Scope	Endpoint	Description
agents:read	GET /a2a/agents/*/.well-known/agent-card.json	Fetch an agent card
agents:run	POST /a2a/agents/*/v1/message:send	Send a message to an agent
agents:run	POST /a2a/agents/*/v1/message:stream	Stream a message to an agent
agents:read	POST /a2a/agents/*/v1/tasks:get	Get an agent task
agents:run	POST /a2a/agents/*/v1/tasks:cancel	Cancel an agent task
teams:read	GET /a2a/teams/*/.well-known/agent-card.json	Fetch a team card
teams:run	POST /a2a/teams/*/v1/message:send	Send a message to a team
teams:run	POST /a2a/teams/*/v1/message:stream	Stream a message to a team
teams:read	POST /a2a/teams/*/v1/tasks:get	Get a team task
teams:run	POST /a2a/teams/*/v1/tasks:cancel	Cancel a team task
workflows:read	GET /a2a/workflows/*/.well-known/agent-card.json	Fetch a workflow card
workflows:run	POST /a2a/workflows/*/v1/message:send	Send a message to a workflow
workflows:run	POST /a2a/workflows/*/v1/message:stream	Stream a message to a workflow
agents:run	POST /a2a/message/send	Dynamic dispatch (deprecated)
agents:run	POST /a2a/message/stream	Dynamic dispatch, streaming (deprecated)

The deprecated dynamic-dispatch endpoints resolve their target at runtime. They carry a coarse agents:run route gate, and the handler re-checks the run scope for the resolved target’s type (agents:run, teams:run, or workflows:run).

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.

Scope	Without it, the user cannot
org:read	Access the organization at all
os:read	List AgentOS instances in the organization
config:read	Use 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

Task	Guide
Bundle scopes into roles	Roles
Mint machine tokens with scopes	Service Accounts
Configure JWT middleware in depth	JWT Middleware