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

# Participant Tokens

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.

| Grant  | Scope format                      | What it controls                                                                                                                                      |
| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `room` | room name string                  | Which room the participant may join (`add_room_grant`)                                                                                                |
| `role` | `"agent" \| "tool" \| "user"`     | Participant role advertised to other services (`add_role_grant`)                                                                                      |
| `api`  | [`ApiScope`](./api_scopes) object | Fine-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](./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`.

```yaml theme={null}
# 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`:

```yaml theme={null}
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](./api_scopes) for that participant. In the current CLI token spec, this must include `llm`.

Generate the token:

```bash theme={null}
meshagent token --input token-spec.yaml
```

Write it to a file instead:

```bash theme={null}
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.

## Related topics

* [`ApiScope` reference](./api_scopes)
* [Managing project room grants](../rest_api/overview)
* [MeshAgent LLM Proxy](../agents/routing/llm_proxy)