> ## Documentation Index > Fetch the complete documentation index at: https://agno-v2-codex-docs-audit-20260719-0149.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/agent-os/security/authorization/service-accounts) 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::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::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](#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::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](/agent-os/security/authorization/service-accounts#privileged-scopes) 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: ```python theme={null} 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](/agent-os/security/authorization/roles) | | Mint machine tokens with scopes | [Service Accounts](/agent-os/security/authorization/service-accounts) | | Configure JWT middleware in depth | [JWT Middleware](/agent-os/middleware/jwt) |