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 bearer token in the Authorization header.

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

​
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

EndpointUse case
POST /livekit/tokenMint participant tokens and create rooms. API reference
GET /livekit/roomsList rooms for the current tenant. API reference
GET /livekit/rooms/{room_name}Inspect room details and participants. API reference
DELETE /livekit/participantRemove a participant from a room. API reference
POST /livekit/participant/muteMute or unmute a participant track. API reference
POST /sip/callInitiate an outbound SIP call. API reference
POST /sip/transferTransfer a SIP participant to a new destination. API reference

​
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:
StatusMeaning
403 ForbiddenRoom exists with a different tenant’s auth_id (token endpoint only).
404 Not FoundRoom not found or access denied (masked for security on other endpoints).
500 Internal Server ErrorLiveKit not configured or operation failed.
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.