Skip to main content
Sayna exposes a thin LiveKit management layer so you can list rooms, inspect participants, and moderate sessions without calling the LiveKit admin API directly. This keeps LiveKit credentials server-side and applies the same auth rules you already use across Sayna.
When AUTH_REQUIRED=true, all endpoints below require a token via the Authorization: Bearer <token> header or the api_key query parameter. The header is recommended by default.

​
Why Sayna wraps LiveKit

  • Prevents exposing LiveKit API keys or admin endpoints to client applications.
  • Enforces Sayna authentication and authorization for every management call.
  • Keeps multi-tenant isolation consistent across REST and WebSocket flows.

​
Published audio tracks

When a WebSocket session is audio-enabled and joins a LiveKit room, the Sayna agent participant publishes synthesized speech on an audio track named "tts-audio". If that session’s config message also includes a loading_audio object, the agent publishes a second audio track named "loading-audio" carrying the loading-indicator sound. The two tracks are independent and can be audible at the same time. LiveKit client SDKs automatically play every subscribed audio track, so participants hear both without any extra client-side handling.
Because "loading-audio" is a real published track, it is included in room-composite egress recordings alongside "tts-audio". This is correct behavior — the recording faithfully reflects what the human participant heard.

​
Room ownership and access control

Room access is controlled via the metadata.auth_id field stored in room metadata. When authentication is enabled:
  • Room creation: When you request a token for a room that doesn’t exist, Sayna creates it and sets metadata.auth_id to your tenant ID.
  • Room access: All room-scoped operations verify that room.metadata.auth_id matches your authenticated auth.id.
  • Access denied: Unauthorized access returns 404 Not Found (masked for security) or 403 Forbidden depending on the operation.
Room names are no longer modified or prefixed. You send and receive clean room names exactly as specified.

​
Backward compatibility

When auth.id is absent (unauthenticated mode), all rooms are accessible. This maintains compatibility with deployments that don’t require authentication.

​
Endpoint overview

​
Typical flow

1

Create a room and get a token

Call POST /livekit/token with your room name. If the room doesn’t exist, Sayna creates it and sets metadata.auth_id to your tenant ID before returning the token.
2

List rooms

Call GET /livekit/rooms to discover active rooms. Only rooms with matching metadata.auth_id are returned.
3

Inspect a room

Use GET /livekit/rooms/{room_name} to fetch participant identities and metadata.
4

Moderate participants

Disconnect a participant with DELETE /livekit/participant or mute a track with POST /livekit/participant/mute.
5

Handle SIP calls

Initiate outbound calls with POST /sip/call or transfer existing SIP participants with POST /sip/transfer.

​
Error handling

Room-scoped operations return specific errors for access control:
When you receive a 403 on token generation, the room already exists and is owned by another tenant. Choose a different room name or contact the room owner.
Removing a participant does not revoke their LiveKit token. If you need to prevent rejoin, issue short-lived tokens and avoid re-minting them after removal.