Skip to main content

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.

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 anything it launches on your behalf. You describe the identity and permissions through a Service or ServiceTemplate manifest and MeshAgent creates that token whenever it needs to connect the service to the room. When building a custom application on MeshAgent you will need to 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 (identity, role, api scope) and injects the signed token into the container as MESHAGENT_TOKEN during startup.
  • Local development and MeshAgent Studio: Running meshagent service run or answering a call from MeshAgent Studio creates a token on demand. This allows your ServiceHost to join the room automatically without creating the token manually.
  • 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, you will need to manually 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.