Authentication

For production applications, we recommend using your secret API key to authenticate users with ID tokens. Your public API key is only for prototyping and public applications.

Quickstart

How ID token authentication works

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.

You prefer to handle permissions yourself?

If you don’t need fine-grained permissions, or if you’d prefer storing individual room permissions in your own system, you can use 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 or /identify-user.

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

Workspace permissions

Using tenants, you can create workspaces in your application, compartmentalizing all resources such as inbox notifications and rooms. This includes everything associated with rooms such as comment threads, realtime data stored, and more. This allows you to add a workspace switcher to your application, separating each of your customers/organizations.

Set up workspace permissions

To set up workspace permissions, pass a tenantId when authenticating a user, ensuring that the user will only have access to resources within this workspace.

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

When creating a resource on the server, such as a room, pass the tenantId to the resource, to allow the user access.

const room = await liveblocks.createRoom("my-room-id", {  defaultAccesses: ["room:write"],  tenantId: "my-tenant-id",});
// { type: "room", id: "my-room-id", metadata: {...}, ... }console.log(room);

Room 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, private rooms, 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. On the client, canWrite is true.
["room:read", "room:presence:write"]: Read access with presence. Enables people to edit their presence, but only view the room’s storage. On the client, canWrite is false.
[]: 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 given 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);

Select your framework

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