Scopes

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

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.

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

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

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.

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

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

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

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

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

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

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

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.

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

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

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

Get Started

AgentOS

Example Usage

Scope Format

Scope Reference

AgentOS Control Plane Scopes

AgentOS Scopes

Access Prerequisites

Custom Scope Mappings

Next Steps

​Scope Format

​Scope Reference

​AgentOS Control Plane Scopes

​AgentOS Scopes

​Access Prerequisites

​Custom Scope Mappings

​Next Steps

Scope Format

Scope Reference

AgentOS Control Plane Scopes

AgentOS Scopes

Access Prerequisites

Custom Scope Mappings

Next Steps