Guides - Managing rooms, users, and permissions

In this guide, we’ll walk you through different concepts to help you manage rooms in your product. Understanding these concepts will help you build experiences that are core to multiplayer products such as share dialogs, paginated overview pages, custom permission flows, and more.

You can call the API Endpoints to manage the rooms.

You can assign custom metadata to your room. For example, if you have different types of room experiences, you can store that type as metadata. This would then come handy when building an overview page listing all the rooms where the type metadata could be used as a filter, making it easy for people to find what they’re looking for.

One way to edit metadata is to use the create room API. In this example we’re creating a new room with a custom roomType property, and setting it to "whiteboard":

1
2
3
4
5
6
7
8
9
10
fetch("https://api.liveblocks.io/v2/rooms", {
method: "POST",
body: JSON.stringify({
id: "my-room-name",
defaultAccesses: [],
metadata: {
roomType: "whiteboard",
},
}),
});

We can then use the get rooms API to retrieve a list of rooms containing the "whiteboard" roomType:

1
2
3
4
const metadata = "metadata.roomType=whiteboard";
const url = `https://api.liveblocks.io/v2/rooms?${metadata}`;
const response = await fetch(url);
const rooms = await response.json();

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

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.

Share dialog illustration

There’s currently one permission type, with more coming soon:

room:write
Enables people to view and edit the room.

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.

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

Access denied illustration

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.

1
2
3
4
5
// private - no one has access by default
"defaultAccesses": []
// public - everyone can edit and view the room
"defaultAccesses": ["room:write"]

We can use the create room API to create a new room with public access levels:

1
2
3
4
5
6
7
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:

1
2
3
4
5
6
7
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.

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.

1
2
3
4
5
import { authorize } from "@liveblocks/node";
const response = await authorize({
groupIds: ["engineering"],
// ...
});

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

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

To allow a "engineering" group access to a room, we can use the update room API with engineering as a groupId:

1
2
3
4
5
6
7
8
9
const roomId = "my-room-name";
fetch(`https://api.liveblocks.io/v2/rooms/${roomId}`, {
method: "POST",
body: JSON.stringify({
groupsAccesses: {
engineering: ["room:write"],
},
}),
});

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

1
2
3
4
5
6
7
8
9
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.

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

Share dialog illustration

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

1
2
3
4
5
import { authorize } from "@liveblocks/node";
const response = await authorize({
userId: "ellen@acme.inc",
// ...
});

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.

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

To create an invitation system, we can use the update room API and use an email address as a userId:

1
2
3
4
5
6
7
8
9
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:

1
2
3
4
5
6
7
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.