> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> Scope format and the full permission reference for every AgentOS endpoint.

Scopes are permission strings carried by the caller's credential: the JWT `scopes` claim, or the stored scopes of a [service account](https://agno-v2.mintlify.site/agent-os/security/authorization/service-accounts.md) token. Each AgentOS endpoint requires one or more scopes; 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` | - | 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](#scope-format).

> [!NOTE]
>
> **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

| 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: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**

| 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` | `POST /components/*/restore` | Restore an archived component |
| `components:delete` | `DELETE /components/*/configs/*` | Delete a component config |

**Agents**

| Scope | Endpoint | Description |
| - | - | - |
| `agents:read` | `GET /agents` | List agents |
| `agents:read` | `GET /agents/*` | View an agent |
| `agents:write` | `POST /agents` | Create an agent |
| `agents:write` | `PATCH /agents/*` | Update an agent |
| `agents:delete` | `DELETE /agents/*` | Delete an agent |
| `agents:run` | `POST /agents/*/runs` | Run an agent |
| `agents:run` | `POST /agents/*/runs/*/continue` | Continue a paused run |
| `agents:run` | `POST /agents/*/runs/*/cancel` | Cancel a run |

**Teams**

| Scope | Endpoint | Description |
| - | - | - |
| `teams:read` | `GET /teams` | List teams |
| `teams:read` | `GET /teams/*` | View a team |
| `teams:write` | `POST /teams` | Create a team |
| `teams:write` | `PATCH /teams/*` | Update a team |
| `teams:delete` | `DELETE /teams/*` | Delete a team |
| `teams:run` | `POST /teams/*/runs` | Run a team |
| `teams:run` | `POST /teams/*/runs/*/continue` | Continue a paused run |
| `teams:run` | `POST /teams/*/runs/*/cancel` | Cancel a run |

**Workflows**

| Scope | Endpoint | Description |
| - | - | - |
| `workflows:read` | `GET /workflows` | List workflows |
| `workflows:read` | `GET /workflows/*` | View a workflow |
| `workflows:write` | `POST /workflows` | Create a workflow |
| `workflows:write` | `PATCH /workflows/*` | Update a workflow |
| `workflows:delete` | `DELETE /workflows/*` | Delete a workflow |
| `workflows:run` | `POST /workflows/*/runs` | Run a workflow |
| `workflows:run` | `POST /workflows/*/runs/*/continue` | Continue a paused run |
| `workflows:run` | `POST /workflows/*/runs/*/cancel` | Cancel a run |

**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:read` | `GET /metrics/refresh/status` | View metrics refresh status |
| `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](https://agno-v2.mintlify.site/agent-os/security/authorization/service-accounts.md#privileged-scopes) 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 |

## 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.

> [!NOTE]
>
> **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](https://agno-v2.mintlify.site/agent-os/security/authorization/roles.md) |
| Mint machine tokens with scopes | [Service Accounts](https://agno-v2.mintlify.site/agent-os/security/authorization/service-accounts.md) |
| Configure JWT middleware in depth | [JWT Middleware](https://agno-v2.mintlify.site/agent-os/middleware/jwt.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.