Permissions - Manage permissions with ID tokens

Managing permissions by issuing ID (identity) tokens follows the analogy of issuing “membership cards”. Anyone with such membership card can try to enter a room, but your permissions will be checked at the door, every time you try to enter a room. This approach to permissions is powerful but can be hard to manage, because you will have to make sure all the access information is entered into our system and kept up to date.

Rooms can have different permission types assigned at three different levels: default, groups, and users. The system is flexible enough to enable you to build a permission system that fits your needs. With that, you can build invite flows that drive more people to your product.

To set up your authentication endpoint to issue ID tokens, make sure to follow the steps for your framework in our ID token authentication guides.

Types

Different permission types can be applied:

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.

Read-only access

To check if a user only has read-only access to storage in your app, the isReadOnly boolean can be retrieved from others or self.

// Vanillaconst { isReadOnly } = room.getSelf();
// Reactconst selfIsReadOnly = useSelf((me) => me.isReadOnly);

You can also use our APIs to access this information, as well as set it, as we’ll detail below.

Levels

Permission types can be applied at three different levels:

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

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 create room API to create a new room with public access levels:

fetch("https://api.liveblocks.io/v2/rooms", {  method: "POST",  body: JSON.stringify({    id: "my-public-room",    defaultAccesses: ["room:write"],  }),});

The default permission types can later be modified with the update room API, in this example turning the room private:

const roomId = "my-room-name";
fetch(`https://api.liveblocks.io/v2/rooms/${roomId}`, {  method: "POST",  body: JSON.stringify({    defaultAccesses: [],  }),});

Default accesses can be also be used within a number of our other APIs.

Groups

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: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
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 the update room API with engineering as a groupId:

const roomId = "my-room-name";
fetch(`https://api.liveblocks.io/v2/rooms/${roomId}`, {  method: "POST",  body: JSON.stringify({    groupsAccesses: {      engineering: ["room:read", "room:presence:write"],    },  }),});

To remove a group’s permissions, we can use the update room API again, and set the permission type to null:

const roomId = "my-room-name";
fetch(`https://api.liveblocks.io/v2/rooms/${roomId}`, {  method: "POST",  body: JSON.stringify({    groupsAccesses: {      engineering: null,    },  }),});

Group accesses can be also be used within a number of our other APIs.

Users

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: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
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 create an invitation system, we can use the update room API and use an email address as a userId:

const roomId = "my-room-name";
fetch(`https://api.liveblocks.io/v2/rooms/${roomId}`, {  method: "POST",  body: JSON.stringify({    usersAccesses: {      "ellen@acme.inc": ["room:write"],    },  }),});

To check a user’s assigned permission types for this room, we can then use the get room API and check usersAccesses:

const roomId = "my-room-name";const url = `https://api.liveblocks.io/v2/rooms/${roomId}`;const response = await fetch(url);const room = await response.json();
// { "ellen@acme.inc": ["room:write"] }console.log(room.data.usersAccesses);

User accesses can be also be used within a number of our other APIs.