> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Scopes

`ApiScope` objects describe exactly which parts of the Rooms API a participant may call. They are carried inside the `api` grant of every [`ParticipantToken`](./participant_tokens) and are defined in `meshagent.api.participant_token.ApiScope`.

## Built-in presets

MeshAgent ships three convenience constructors:

* `ApiScope.agent_default()` – enables Livekit, Queues, Messaging, Dataset, Memory, Sync, Storage, Containers, Developer, Agents, LLM, Services, and Secrets access. Use `ApiScope.agent_default(tunnels=True)` to include the tunnels grant.
* `ApiScope.user_default()` – enables the same core room access as `agent_default()`, but omits the LLM grant and still excludes Admin and Tunnels.
* `ApiScope.full()` – everything in `agent_default()` plus the Admin and Tunnels grants.

Use these helpers when you want broad access, then override individual fields when you need to lock things down.

## Scope fields

Each field is optional. Most fields treat `None` as "no restriction" for that capability. Tunnels are opt-in: when `tunnels` is `None`, tunnel access is denied.

### `livekit`

`LivekitGrant` contains an optional `breakout_rooms` list. When provided, only the named breakout rooms can be joined; leaving it empty allows every breakout room (`LivekitGrant.can_join_breakout_room`).

### `queues`

`QueuesGrant` exposes three controls:

* `send`: list of queue names the participant may publish to (`can_send` checks membership; `None` means all queues).
* `receive`: list of queues the participant may consume from (`can_receive`).
* `list`: boolean flag gating `QueuesClient.list` operations (defaults to `True`).

### `messaging`

`MessagingGrant` has simple booleans for `broadcast`, `list`, and `send`, all defaulting to `True`.

### `dataset`

`DatasetGrant` manages table-level access:

* `tables`: optional list of `TableGrant` entries (`name`, and booleans for `read`, `write`, `alter`). When omitted the participant may access every table.
* `list_tables`: boolean (defaults to `True`).
* Helper methods (`can_read`, `can_write`, `can_alter`) enforce the per-table flags.

### `memory`

`MemoryGrant` controls room-memory access:

* `list`: boolean controlling whether the participant may list memories.
* `memories`: optional list of `MemoryEntryGrant` objects, each scoped by `name` and optional `namespace`.
* Each memory entry has its own `permissions` object with booleans for `create`, `drop`, `inspect`, `query`, `upsert`, `ingest`, `recall`, and `optimize`.

### `sync`

`SyncGrant` accepts `paths`: a list of `SyncPathGrant { path, read_only }`. Paths may end with `*` to match prefixes. When no paths are supplied, read and write access is global. `can_read` and `can_write` verify the constraints.

### `storage`

`StorageGrant` mirrors the sync semantics but checks filesystem-style prefixes (`path.startswith(...)`). A `read_only` flag prevents writes on matching paths.

### `containers`

`ContainersGrant` controls container management features:

* `use_containers`: overall switch for container operations (defaults to `True`).
* `pull` / `run`: optional allowlists of image tags; each entry can end with `*` to allow a prefix (`can_pull` / `can_run`).
* `logs`: booleans toggling log streaming support.

### `developer`

`DeveloperGrant` currently exposes a single `logs` boolean, enabling developer log forwarding when `True`.

### `tunnels`

`TunnelsGrant` controls port-forwarding into room containers.

* `ports`: optional list of allowed container ports. If omitted or empty, all ports are allowed. If `tunnels` is `None`, port forwarding is denied.

### `agents`

`AgentsGrant` exposes boolean switches for registering agents or toolkits (`register_agent`, `register_public_toolkit`, `register_private_toolkit`) and for invoking the Agents API (`call`, `use_agents`, `use_tools`). They default to `True` to match the typical agent workflow.

### `admin`

`AdminGrant` currently exposes a single `config` boolean. When `True`, the participant may use the admin configuration surface.

### `secrets`

User and service-account secrets are managed through the account REST API. Proxy use is controlled by OAuth scopes such as `secrets:proxy` plus service-account permissions.

### `services`

`ServicesGrant` currently exposes a `list` boolean for service-listing operations in the room.

## Examples

```yaml theme={null}
# Restrict a service to a single queue and read-only storage
api:
  queues:
    send: ["notifications"]
    receive: ["notifications"]
  storage:
    paths:
      - path: "/data/uploads"
        read_only: true
```

```yaml theme={null}
# Allow port forwarding only to container port 9000
api:
  tunnels:
    ports: ["9000"]
```

```python theme={null}
from meshagent.api.participant_token import ApiScope, QueuesGrant

scope = ApiScope(
    queues=QueuesGrant(send=["events"], receive=["events"])
)
```

Combine these snippets with the `api` field when [packaging a service](../services/deployment/deploy_services) to set the appropriate permissions for your service.