REST endpoints

LiveKit token

Generates a LiveKit JWT token for a participant to join a specific room.

When authentication is enabled (auth.id is present), this handler:

Creates the room if it doesn’t exist
Sets room.metadata.auth_id to the authenticated tenant’s ID
Issues the token only after metadata is verified/set

Arguments

state - Shared application state containing LiveKit configuration
request - Token request with room name and participant details

Returns

Response - JSON response with token or error status

Errors

400 Bad Request - Invalid request data (empty fields)
403 Forbidden - Room exists with a different tenant’s auth_id
500 Internal Server Error - LiveKit service not configured, room creation failed, or token generation failed

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"
}
'

import requests

url = "https://api.sayna.ai/livekit/token"

payload = {
    "participant_identity": "user-alice-456",
    "participant_name": "Alice Smith",
    "room_name": "conversation-room-123"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    participant_identity: 'user-alice-456',
    participant_name: 'Alice Smith',
    room_name: 'conversation-room-123'
  })
};

fetch('https://api.sayna.ai/livekit/token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sayna.ai/livekit/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'participant_identity' => 'user-alice-456',
    'participant_name' => 'Alice Smith',
    'room_name' => 'conversation-room-123'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sayna.ai/livekit/token"

	payload := strings.NewReader("{\n  \"participant_identity\": \"user-alice-456\",\n  \"participant_name\": \"Alice Smith\",\n  \"room_name\": \"conversation-room-123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sayna.ai/livekit/token")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"participant_identity\": \"user-alice-456\",\n  \"participant_name\": \"Alice Smith\",\n  \"room_name\": \"conversation-room-123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sayna.ai/livekit/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"participant_identity\": \"user-alice-456\",\n  \"participant_name\": \"Alice Smith\",\n  \"room_name\": \"conversation-room-123\"\n}"

response = http.request(request)
puts response.read_body

{
  "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):

If the room doesn’t exist, Sayna creates it automatically.
The room’s metadata.auth_id is set to your tenant ID.
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

Scenario	Behavior
Room doesn’t exist	Room is created with `metadata.auth_id` set to your tenant ID.
Room exists, you own it	Token is issued normally.
Room exists, different owner	`403 Forbidden` is returned.
Unauthenticated mode	Token is issued without ownership checks.

Error responses

Status	Condition
`400 Bad Request`	Missing or empty required fields.
`403 Forbidden`	Room exists with a different tenant’s `auth_id`.
`500 Internal Server Error`	LiveKit 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..."

LiveKit roomsLists all LiveKit rooms belonging to the authenticated client. Rooms are filtered by `metadata.auth_id` for tenant isolation. # Arguments * `state` - Shared application state containing LiveKit configuration * `auth` - Authentication context from middleware # Returns * `Response` - JSON response with rooms list or error status # Filtering - When `auth.id` is present: Returns only rooms where `metadata.auth_id == auth.id` - When `auth.id` is absent: Returns all rooms (backward-compatible mode) # Errors * 500 Internal Server Error - LiveKit service not configured or API call failed

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"
}
'

import requests

url = "https://api.sayna.ai/livekit/token"

payload = {
    "participant_identity": "user-alice-456",
    "participant_name": "Alice Smith",
    "room_name": "conversation-room-123"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    participant_identity: 'user-alice-456',
    participant_name: 'Alice Smith',
    room_name: 'conversation-room-123'
  })
};

fetch('https://api.sayna.ai/livekit/token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sayna.ai/livekit/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'participant_identity' => 'user-alice-456',
    'participant_name' => 'Alice Smith',
    'room_name' => 'conversation-room-123'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sayna.ai/livekit/token"

	payload := strings.NewReader("{\n  \"participant_identity\": \"user-alice-456\",\n  \"participant_name\": \"Alice Smith\",\n  \"room_name\": \"conversation-room-123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sayna.ai/livekit/token")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"participant_identity\": \"user-alice-456\",\n  \"participant_name\": \"Alice Smith\",\n  \"room_name\": \"conversation-room-123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sayna.ai/livekit/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"participant_identity\": \"user-alice-456\",\n  \"participant_name\": \"Alice Smith\",\n  \"room_name\": \"conversation-room-123\"\n}"

response = http.request(request)
puts response.read_body

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

​Room creation behavior

​Authorization

​Error responses

Authorizations

Body

Example

Response

Example

Room creation behavior

Authorization

Error responses