Authentication

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

Copied!
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);

Copied!
import (
	"time"

	lksdk "github.com/livekit/server-sdk-go"
	"github.com/livekit/protocol/auth"
)

func getJoinToken(apiKey, apiSecret, room, identity string) (string, error) {
    canPublish := true
    canSubscribe := true

	at := auth.NewAccessToken(apiKey, apiSecret)
	grant := &auth.VideoGrant{
		RoomJoin:     true,
		Room:         room,
		CanPublish:   &canPublish,
		CanSubscribe: &canSubscribe,
	}
	at.AddGrant(grant).
		SetIdentity(identity).
		SetValidFor(time.Hour)

	return at.ToJWT()
}

Copied!
require 'livekit'

token = LiveKit::AccessToken.new(api_key: 'yourkey', api_secret: 'yoursecret')
token.identity = 'participant-identity'
token.name = 'participant-name'
token.add_grant(roomJoin: true, room: 'room-name')

puts token.to_jwt

Copied!
import io.livekit.server.*;

public String createToken() {
  AccessToken token = new AccessToken("apiKey", "secret");
  token.setName("participant-name");
  token.setIdentity("participant-identity");
  token.setMetadata("metadata");
  token.addGrants(new RoomJoin(true), new Room("room-name"));

  return token.toJwt();
}

For other platforms, you can either implement token generation yourself or use the livekit-cli command.

Token signing is fairly straight forward, see js implementation as a reference.

LiveKit CLI is available at https://github.com/livekit/livekit-cli

Token example

Here's an example of the decoded body of a join token:

Copied!
{
  "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
video	Video grant, including room permissions (see below)
metadata	Participant 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:

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 (used by recorder)
recorder	bool	indicates this participant is recording the room

To create a token where the participant can only subscribe, and not publish into the room, you would use the following grant:

Copied!
{
  ...
  "video": {
    "room": "myroom",
    "roomJoin": true,
    "canSubscribe": true,
    "canPublish": false,
    "canPublishData": false
  }
}

Example: camera-only

Allow the participant to publish camera, but disallow other sources

Copied!
{
  ...
  "video": {
    "room": "myroom",
    "roomJoin": true,
    "canSubscribe": true,
    "canPublish": true,
    "canPublishSources": ["camera"]
  }
}

Since LiveKit server v0.15.6, the server will automatically issue refreshed tokens to connected clients. This ensures that connected clients can 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.