Skip to main content
Every participant in a MeshAgent room operates with a secure token that defines their identity and permissions. These JWT-based tokens ensure that users, containers, and services can only access the resources they’re authorized to use.

​
Token Anatomy

MeshAgent exposes tokens through meshagent.api.participant_token.ParticipantToken which consists of:
  • name: the participant identifier embedded in the JWT payload
  • project_id (optional): the project id, populated when the participant belongs to a project
  • api_key_id (optional): the API key id used to mint the token
  • version (optional): the participant-token schema version (defaulted when omitted)
  • grants (optional): a list of individual ParticipantGrant entries that describe permissions

​
Permission Types

Participant tokens use grants and scopes to define permissions. Each grant has a grant name which indicates the type of permission (room, role, api), and each grant has a scope which provides the specific details of what is allowed.
GrantScope formatWhat it controls
roomroom name stringWhich room the participant may join (add_room_grant)
role"agent" | "tool" | "user"Participant role advertised to other services (add_role_grant)
apiApiScope objectFine-grained access to each Room API surface (add_api_grant). A single ApiScope can enable multiple sections (storage, containers, secrets, etc.)
Tunnels and port forwarding Port forwarding is authorized via the api.tunnels grant (see API Scopes). If tunnels is omitted, tunnel access is denied. If tunnels.ports is omitted or empty, all ports are allowed; otherwise only the listed ports are allowed. Some older tokens include a top-level tunnel_ports grant, but current tunnel enforcement uses api.tunnels. 
# Allow port forwarding to container port 9000
api:
  tunnels:
    ports: ["9000"]

​
How tokens are issued

MeshAgent signs participant tokens automatically for room connections it creates on your behalf. Deployed services describe the identity and permissions in their manifest. Local development commands can also mint a room-scoped token for the process they start. When building a custom application on MeshAgent, generate ParticipantTokens so participants can connect to your rooms with the appropriate permissions.
  • Project services and room containers: MeshAgent reads the manifest for each endpoint or container (identity, role, api scope) and injects the signed token into the runtime as MESHAGENT_TOKEN during startup.
  • Local room-connected processes: meshagent room connect --identity <name> -- <command> mints a participant token locally for that identity and starts the command with MESHAGENT_TOKEN, OPENAI_API_KEY, and ANTHROPIC_API_KEY set to that room-scoped token. Use --meshagent-token when you need to choose the API scope (agentDefault, userDefault, full, or a JSON ApiScope).
  • End-user connections: When a participant connects to the room, MeshAgent looks up the participant’s permissions and returns the JWT to the browser or client that is joining the room.
  • Custom apps built on MeshAgent: When building a custom app on MeshAgent, create a ParticipantToken and define permissions for your users.

​
Generate a token from the CLI

Use meshagent token when you need to sign a participant token yourself. This is useful for custom clients, coding agents, or temporary room identities that need to access room APIs directly. Create a token spec file such as token-spec.yaml: 
version: v1
kind: ParticipantToken
identity: my-client
room: my-room
role: user
api:
  llm: {}
Current CLI token specs require an explicit api.llm field. Include api.llm: {} when the token should make LLM proxy requests; tokens without api.llm are rejected by the proxy. The main fields are:
  • identity: the participant name in the room
  • room: the room this token should join
  • role: user, agent, or tool
  • api: the API scope for that participant. In the current CLI token spec, this must include llm.
Generate the token: 
meshagent token --input token-spec.yaml
Write it to a file instead: 
meshagent token --input token-spec.yaml --output room.token
By default, the command uses the active project and active API key. Use --project-id or --key when you want to override those defaults.