> ## 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, SQLite, Memory, Sync, Storage, Containers, Developer, Agents, LLM, and Services access. Use `ApiScope.agent_default(tunnels=True)` to include the tunnels grant.
* `ApiScope.user_default()` – enables the same core room access as `agent_default()`, including SQLite, but omits the LLM grant and still excludes Admin and Tunnels.
* `ApiScope.full()` – everything in `agent_default()` plus the Admin and Tunnels grants. It does not add the room `secrets` grant.

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

## Scope fields

Each top-level field is a grant for one Room API surface. If a grant object is absent, that API surface is denied. When a grant object is present, `None` in an allowlist generally means unrestricted access within that grant. Tunnels are opt-in: when `tunnels` is absent, tunnel access is denied.

### `livekit`

`LivekitGrant` contains an optional `breakout_rooms` list. When omitted, any breakout room may be joined. When provided, only the named breakout rooms can be joined.

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

Table grants can also include `namespace`. A grant with no namespace matches the table in any namespace; a grant with a namespace only matches requests for that namespace.

### `sqlite`

`SqliteGrant` controls room-scoped SQLite databases:

* `create_database`: boolean controlling database creation.
* `list_databases`: boolean controlling database discovery.
* `databases`: optional list of `SqliteDatabaseGrant` entries. When omitted, the participant may use every SQLite database allowed by the grant.

Each database grant can include:

* `name`: database name.
* `namespace`: optional namespace restriction.
* `create_table`, `drop`, `inspect`, `list_tables`, and `execute`: booleans for database-level operations.
* `tables`: optional list of table-specific grants. When omitted on a matching database grant, table read, write, and alter access applies to all tables in that database.

Each SQLite table grant includes `database`, `table`, optional `namespace`, and booleans for `read`, `write`, and `alter`.

### `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.
* `registry`: optional `ContainerRegistryGrant` for repository-level registry operations.

`ContainerRegistryGrant` includes:

* `list`: repositories the participant may list.
* `pull`: repositories the participant may pull from.
* `run`: repositories the participant may run images from.
* `write`: repositories the participant may write to.

Repository patterns can be exact names or prefixes ending in `*`. If `registry` is absent, registry repository checks allow any repository; image pull and run checks are still controlled separately by the top-level `pull` and `run` image allowlists. If `registry.list` is absent but `pull`, `run`, or `write` are present, list access is inferred from those repository allowlists.

### `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 the `tunnels` grant is absent, 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.

Use `allowed_toolkits` to restrict tool use to specific toolkit names. When `allowed_toolkits` is omitted, the participant may use any toolkit allowed by the rest of the grant.

### `llm`

`LLMGrant` controls room-scoped LLM proxy access.

* `models`: optional provider/model allowlist. When omitted, the participant may use any model allowed by the project policy. Entries can be exact `provider/model` names or prefixes ending in `*`.

### `admin`

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

### `secrets`

The room API `SecretsGrant` enables room routes that require a participant-token secrets grant. It has no nested fields.

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"]
```

```yaml theme={null}
# Allow only selected room SQLite access
api:
  sqlite:
    create_database: false
    list_databases: true
    databases:
      - name: reports
        inspect: true
        list_tables: true
        execute: true
        tables:
          - database: reports
            table: daily_metrics
            read: true
            write: false
            alter: false
```

```yaml theme={null}
# Limit LLM proxy access and tool use
api:
  llm:
    models: ["openai/gpt-5.5", "anthropic/claude-opus-*"]
  agents:
    allowed_toolkits: ["support-search", "ticket-reader"]
```

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