Overview
For a LiveKit client to successfully connect to the server, it must pass an access token with the request.
This token encodes the identity of a participant, name of the room, capabilities and permissions. Access tokens are JWT-based and signed with your API secret to prevent forgery.
Access tokens also carry an expiration time, after which the server will reject connections with that token. Note: expiration time only impacts the initial connection, and not subsequent reconnects.
Creating a token
lk token create \--api-key <KEY> \--api-secret <SECRET> \--identity <NAME> \--room <ROOM_NAME> \--join \--valid-for 1h
Token example
Here's an example of the decoded body of a join token:
{"exp": 1621657263,"iss": "APIMmxiL8rquKztZEoZJV9Fb","sub": "myidentity","nbf": 1619065263,"video": {"room": "myroom","roomJoin": true},"metadata": ""}
field | description |
---|---|
exp | Expiration time of token |
nbf | Start time that the token becomes valid |
iss | API key used to issue this token |
sub | Unique identity for the participant |
metadata | Participant metadata |
attributes | Participant attributes (key/value pairs of strings) |
video | Video grant, including room permissions (see below) |
sip | SIP grant |
Video grant
Room permissions are specified in the video
field of a decoded join token. It may contain one or more of the following properties:
field | type | description |
---|---|---|
roomCreate | bool | Permission to create or delete rooms |
roomList | bool | Permission to list available rooms |
roomJoin | bool | Permission to join a room |
roomAdmin | bool | Permission to moderate a room |
roomRecord | bool | Permissions to use Egress service |
ingressAdmin | bool | Permissions to use Ingress service |
room | string | Name of the room, required if join or admin is set |
canPublish | bool | Allow participant to publish tracks |
canPublishData | bool | Allow participant to publish data to the room |
canPublishSources | string[] | When set, only listed source can be published. (camera, microphone, screen_share, screen_share_audio) |
canSubscribe | bool | Allow participant to subscribe to tracks |
canUpdateOwnMetadata | bool | Allow participant to update its own metadata |
hidden | bool | Hide participant from others in the room |
kind | string | Type of participant (standard, ingress, egress, sip, or agent). this field is typically set by LiveKit internals. |
Example: subscribe-only token
To create a token where the participant can only subscribe, and not publish into the room, you would use the following grant:
{..."video": {"room": "myroom","roomJoin": true,"canSubscribe": true,"canPublish": false,"canPublishData": false}}
Example: camera-only
Allow the participant to publish camera, but disallow other sources
{..."video": {"room": "myroom","roomJoin": true,"canSubscribe": true,"canPublish": true,"canPublishSources": ["camera"]}}
SIP grant
In order to interact with the SIP service, permission must be granted in the sip
field of the JWT. It may contain the following properties:
field | type | description |
---|---|---|
admin | bool | Permission to manage SIP trunks and dispatch rules |
call | bool | Permission to make SIP calls via CreateSIPParticipant |
Token refresh
LiveKit server proactively issues refreshed tokens to connected clients, ensuring they can reconnect if disconnected. These refreshed access tokens have a 10-minute expiration.
Additionally, tokens are refreshed when there are changes to a participant's name, permissions or metadata.
Updating permissions
A participant's permissions can be updated at any time, even after they've already connected. This is useful in applications where the participant's role could change during the session, such as in a participatory livestream.
It's possible to issue a token with canPublish: false
initially, and then updating it to canPublish: true
during the session. Permissions can be changed with the UpdateParticipant server API.