LiveKit Logo

docs

Github

Guides / Access Tokens

Access Tokens

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

import { AccessToken } from 'livekit-server-sdk';
const roomName = 'name-of-room';
const participantName = 'user-name';
const at = new AccessToken('api-key', 'secret-key', {
identity: participantName,
});
at.addGrant({ roomJoin: true, room: roomName, canPublish: true, canSubscribe: true });
const token = at.toJwt();
console.log('access token', token);

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": ""
}
fielddescription
expExpiration time of token
nbfStart time that the token becomes valid
issAPI key used to issue this token
subUnique identity for the participant
videoVideo grant, including room permissions (see below)
metadataParticipant metadata

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:

fieldtypedescription
roomCreateboolpermission to create rooms
roomListboolpermission to list available rooms
roomJoinboolpermission to join a room
roomAdminboolpermission to moderate a room
roomRecordboolpermissions to use Egress service
roomstringname of the room, required if join or admin is set
canPublishboolallow participant to publish tracks
canPublishDataboolallow participant to publish data to the room
canSubscribeboolallow participant to subscribe to tracks
hiddenboolhide participant from others (used by recorder)
recorderboolindicates this participant is recording the room

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

Token refresh

Since LiveKit server v0.15.6, the server will automatically issue refreshed tokens to connected clients. This ensures that connected clients could re-establish connection with the server should they become disconnected. Refreshed access token has an expiration of 10 minutes.

Access tokens are also refreshed if a participant's permissions or metadata have changed.

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.