Authentication - Authenticate with ID tokens

ID token authentication allows Liveblocks to handle permissions for you. This means that when you create or modify a room, you can set a user’s permissions on the room itself. This means the room acts as a source of truth. Later, when a user tries to enter a room, Liveblocks will automatically check if the user has permission, and deny them access if the permissions aren’t set.

Permissions aren’t just for individual users, but can also be set for groups of users, or for the whole room at once.

Don’t need complex permissions?

If you don’t need fine-grained permissions, or if you’d prefer storing individual room permissions in your own system, we recommend using simpler access tokens instead.

Authenticating

Authenticating with ID tokens means creating a JSON Web Token (JWT) that’s used to verify the identity of the current user when connecting to a Liveblocks room. This token is created using liveblocks.identifyUser.

const { body, status } = await liveblocks.identifyUser({  userId: "olivier@example.com",});
// '{ token: "eyJga7..." }'console.log(body);

Before using ID tokens, it’s recommended to read this entire page, as it explains how to set up permissions in your Liveblocks app. However, if you’d like to quickly set up Liveblocks, you can select your framework and read more later.

Permissions

ID token authentication allows you to set different permission types on rooms, assigned at three different levels: default, groups, and users. The system is flexible enough to enable you to build a permission system that’s helpful for building invite dialogs, workspaces, and more.

To set room permissions, you can create or update a room, passing permission information in the options.

const room = await liveblocks.createRoom("a32wQXid4A9", {  // This is a private room  defaultAccesses: [],
  // But Olivier can enter  usersAccesses: {    "olivier@example.com": ["room:read"],  },});

Permission types

There are three permission values that you can set on rooms.

["room:write"]: Full access. Enables people to view and edit the room. isReadOnly is false.
["room:read", "room:presence:write"]: Read access with presence. Enables people to edit their presence, but only view the room’s storage. isReadOnly is true.
[]: Private. No one can enter the room.

Permission levels

Permission types can be applied at three different levels, enabling complex entry systems.

defaultAccesses: The default permission types to apply to the entire room.
groupsAccesses: Permission types to apply to specific groups of users.
usersAccesses: Permission types to apply to specific users.

Each level further down will override access levels defined above, for example a room with private access will allow a user with room:write access to enter.

Default room permissions

The defaultAccesses level is used to set the default permissions of the entire room.

When used in our APIs, this property takes an array, with an empty array [] signifying no access. Add permission types to this array to define the default access level to your room.

// Private - no one has access by default"defaultAccesses": []
// Public - everyone can edit and view the room"defaultAccesses": ["room:write"]
// Read-only - everyone can view the room, but only presence can be edited"defaultAccesses": ["room:read", "room:presence:write"]

Setting room access

We can use the liveblocks.createRoom to create a new room with public access levels:

const room = await liveblocks.createRoom("a32wQXid4A9", {  defaultAccesses: ["room:write"],});

The default permission types can later be modified with liveblocks.updateRoom, in this example turning the room private:

const room = await liveblocks.updateRoom("a32wQXid4A9", {  defaultAccesses: [],});

Groups permissions

The groupsAccesses level is used to set the default permissions of any given group within room.

Groups are represented by a groupId—a custom string that represents a selection of users in your app. Groups can be attached to a user by passing an array of groupId values in groupIds, during authentication.

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "",});
export async function POST(request: Request) {  const { status, body } = await liveblocks.identifyUser({    userId: "marie@example.com",    groupIds: ["engineering"]  });
  return new Response(body, { status });}

In our APIs you can then set group accesses by using the groupId as the key, and an array of permissions as the value.

// "engineering" group has access to view and edit"groupsAccesses": {  "engineering": ["room:write"],}

Modifying group access

To allow an “engineering” group access to view a room, and modify their presence, we can use liveblocks.updateRoom with engineering as a groupId:

const room = await liveblocks.updateRoom("a32wQXid4A9", {  groupsAccesses: {    engineering: ["room:read", "room:presence:write"],  },});

After calling this, every user in the “engineering” group will have read-only access. To remove a group’s permissions, we can use liveblocks.updateRoom again, and set the permission type to null:

const room = await liveblocks.updateRoom("a32wQXid4A9", {  groupsAccesses: {    engineering: null,  },});

User permissions

The usersAccesses level is used to set permissions of any give user within a room.

To use this, first a user is given a userId during authentication.

import { Liveblocks } from "@liveblocks/node";
const liveblocks = new Liveblocks({  secret: "",});
export async function POST(request: Request) {  const { status, body } = await liveblocks.identifyUser({    userId: "ellen@acme.inc"  });
  return new Response(body, { status });}

Then, if you want the user with the userId id to make edits, set userId to ["room:write"] within usersAccesses when creating or updating a room.

// user with userId "ellen@acme.inc" has access to view and edit"usersAccesses": {  "ellen@acme.inc": ["room:write"]}

Checking user access

To give them room permission, we can use liveblocks.updateRoom, setting write access on their userId:

const room = await liveblocks.updateRoom("a32wQXid4A9", {  usersAccesses: {    "ellen@acme.inc": ["room:write"],  },});

To check a user’s assigned permission types for this room, we can then use liveblocks.updateRoom and check usersAccesses:

const room = await liveblocks.getRoom("a32wQXid4A9");
// { "ellen@acme.inc": ["room:write"] }console.log(room.data.usersAccesses);

Tenants

You can use tenants to compartmentalize your rooms per customers/organizations that you have.

When using ID tokens, you can set the tenantId when using identifyUser.

When a token is generated for a specific tenant, it will only give access to resources inside this tenant, even if the user has access to rooms in other tenants.

const { body, status } = await liveblocks.identifyUser({  userId: "olivier@example.com",  tenantId: "tenant123",});
// '{ token: "eyJga7..." }'console.log(body);

Select your framework

Select your framework for specific instructions on setting up ID token authentication.