Skip to main content
POST
/
livekit
/
token
Handler for POST /livekit/token endpoint
curl --request POST \
  --url https://api.sayna.ai/livekit/token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "participant_identity": "user-alice-456",
  "participant_name": "Alice Smith",
  "room_name": "conversation-room-123"
}
'
{
  "livekit_url": "ws://localhost:7880",
  "participant_identity": "user-alice-456",
  "room_name": "conversation-room-123",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Generates a LiveKit JWT token for a participant to join a specific room. When authentication is enabled, this endpoint also handles room creation and ownership.

​
Room creation behavior

When auth.id is present (authenticated mode):
  1. If the room doesn’t exist, Sayna creates it automatically.
  2. The room’s metadata.auth_id is set to your tenant ID.
  3. The token is issued only after ownership is verified or established.
Room names are used exactly as provided. No prefixing or modification is applied.

​
Authorization

ScenarioBehavior
Room doesn’t existRoom is created with metadata.auth_id set to your tenant ID.
Room exists, you own itToken is issued normally.
Room exists, different owner403 Forbidden is returned.
Unauthenticated modeToken is issued without ownership checks.

​
Error responses

StatusCondition
400 Bad RequestMissing or empty required fields.
403 ForbiddenRoom exists with a different tenant’s auth_id.
500 Internal Server ErrorLiveKit not configured or token generation failed.
If you receive a 403, the room already exists and is owned by another tenant. Choose a different room name rather than retrying with the same one.

Authorizations

​
Authorization
string
header
required

Authentication token for protected endpoints. Can be provided as Authorization: Bearer <token> or ?api_key=<token>. Required when AUTH_REQUIRED is enabled.

Body

application/json

Request body for generating a LiveKit token

Example

{
  "room_name": "conversation-room-123",
  "participant_name": "Alice Smith",
  "participant_identity": "user-alice-456"
}
​
participant_identity
string
required

Unique identifier for the participant (e.g., "user-123")

Example:

"user-alice-456"

​
participant_name
string
required

Display name for the participant (e.g., "John Doe")

Example:

"Alice Smith"

​
room_name
string
required

The LiveKit room name to generate a token for

Example:

"conversation-room-123"

Response

Token generated successfully. Room is created if it doesn't exist and metadata.auth_id is set.

Response containing the generated LiveKit token

Example

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "room_name": "conversation-room-123",
  "participant_identity": "user-alice-456",
  "livekit_url": "ws://localhost:7880"
}
​
livekit_url
string
required

The LiveKit server URL to connect to

Example:

"ws://localhost:7880"

​
participant_identity
string
required

Echo back the participant identity for client confirmation

Example:

"user-alice-456"

​
room_name
string
required

Echo back the room name for client confirmation

Example:

"conversation-room-123"

​
token
string
required

The generated JWT token for LiveKit

Example:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."