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

# 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

# Allow port forwarding only to container port 9000
api:
  tunnels:
    ports: ["9000"]

# 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

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

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 to set the appropriate permissions for your service.

Introduction

Rooms

Agents & Tools

Deploy & Manage

Projects

Product Interfaces

Developer Reference

Built-in presets

Scope fields

`livekit`

`queues`

`messaging`

`dataset`

`sqlite`

`memory`

`sync`

`storage`

`containers`

`developer`

`tunnels`

`agents`

`llm`

`admin`

`secrets`

`services`

Examples

​Built-in presets

​Scope fields

​livekit

​queues

​messaging

​dataset

​sqlite

​memory

​sync

​storage

​containers

​developer

​tunnels

​agents

​llm

​admin

​secrets

​services

​Examples

Built-in presets

Scope fields

`livekit`

`queues`

`messaging`

`dataset`

`sqlite`

`memory`

`sync`

`storage`

`containers`

`developer`

`tunnels`

`agents`

`llm`

`admin`

`secrets`

`services`

Examples