Skip to main content

Access Tokens

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.

Creating a token

TypeScript
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": ""
}

We use iss to identify the API key, sub to indicate participant identity, and video to encode LiveKit VideoGrant.

Room permissions

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

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 expiration

A tokens has an expiration time. We recommend setting it to the expected duration of a session. A LiveKit client will store a token for the entire session duration, in case it needs to reconnect.

Participant metadata

You may also attach any arbirary metadata onto each participant via the metadata field. This data is opaque to LiveKit.

When provided, LiveKit will attach the metadata to the participant object that the clients would receive.