Per-call options sent to configurable token sources (endpoint, sandbox, custom). More...

#include <token_source.h>

Public Attributes
std::optional< std::string >	room_name
	Target room name encoded into the token request.

std::optional< std::string >	participant_name
	Participant display name shown in UIs and room rosters.

std::optional< std::string >	participant_identity
	Stable participant identity encoded into the JWT.

std::optional< std::string >	participant_metadata
	Opaque participant metadata string stored on the participant record.

std::map< std::string, std::string >	participant_attributes
	Key/value participant attributes encoded into the token request.

std::optional< std::string >	agent_name
	Name of a registered LiveKit agent to dispatch into the room.

std::optional< std::string >	agent_metadata
	Opaque metadata passed to the dispatched agent job at startup.

std::optional< std::string >	agent_deployment
	LiveKit Cloud deployment to target for agent dispatch.

Detailed Description

Per-call options sent to configurable token sources (endpoint, sandbox, custom).

All fields are optional. Unset or empty values are omitted from the token-server request body. The token server embeds the provided values into the returned JWT; Room::connect does not read these options directly after fetch — the room, identity, and grants come from the token.

Note: Which fields are honored depends on the token server. The LiveKit Cloud sandbox token server auto-generates room_name, participant_identity, and related fields when they are omitted. A project token endpoint typically accepts the full set below, including agent dispatch via room_config.

Member Data Documentation

◆ agent_deployment

std::optional<std::string> livekit::TokenRequestOptions::agent_deployment

LiveKit Cloud deployment to target for agent dispatch.

Optional. When omitted or empty, the production deployment is used. Only relevant when dispatching a named agent on LiveKit Cloud.

◆ agent_metadata

std::optional<std::string> livekit::TokenRequestOptions::agent_metadata

Opaque metadata passed to the dispatched agent job at startup.

Often JSON. Applies to the remote agent worker, not the local participant (use participant_metadata for that). Ignored unless agent_name is set or another agent field triggers room_config serialization.

◆ agent_name

std::optional<std::string> livekit::TokenRequestOptions::agent_name

Name of a registered LiveKit agent to dispatch into the room.

When set (alone or with agent_metadata / agent_deployment), the SDK sends room_config.agents in the token request so the token server can embed agent dispatch in the JWT. The named agent must already be deployed and registered with the same agent_name; this does not run agent logic in the client.

See also: https://docs.livekit.io/agents/server/agent-dispatch/

◆ participant_attributes

std::map<std::string, std::string> livekit::TokenRequestOptions::participant_attributes

Key/value participant attributes encoded into the token request.

Optional. Empty keys are omitted when serializing the request. Attribute semantics are defined by your token server and application.

◆ participant_identity

std::optional<std::string> livekit::TokenRequestOptions::participant_identity

Stable participant identity encoded into the JWT.

Set this when the same logical user or device should reconnect with the same identity (for example, "robot-a" in tests). If omitted, many token servers assign a new identity on each fetch.

◆ participant_metadata

std::optional<std::string> livekit::TokenRequestOptions::participant_metadata

Opaque participant metadata string stored on the participant record.

Often JSON. Passed through to the token server for inclusion in the JWT. Optional unless your backend or agents depend on it.

◆ participant_name

std::optional<std::string> livekit::TokenRequestOptions::participant_name

Participant display name shown in UIs and room rosters.

Optional cosmetic label. Does not need to match participant_identity. If omitted, the token server may generate one or leave it unset.

◆ room_name

std::optional<std::string> livekit::TokenRequestOptions::room_name

Target room name encoded into the token request.

Set this when you need a stable room across reconnects or when coordinating multiple clients in the same session. If omitted, many token servers (including the sandbox) assign a new room name on each fetch, so repeat connections may land in different rooms.

The documentation for this struct was generated from the following file:

include/livekit/token_source.h

Public Attributes