Permissions

Permissions define what an authenticated user can do with Liveblocks resources such as rooms, comments, and feeds. When using ID token authentication, permissions are set on rooms. With access tokens, you permissions are granted when a user authenticates.

Example usage

Permissions are set as an array of strings, in any order, and setting an empty array means no access. You can use these permissions with Liveblocks APIs, for example when creating a room.

const room = await liveblocks.createRoom("my-room-id", {  // By default, nobody has access to the room  defaultAccesses: [],
  // `groupIds: ["viewer"]` users are read-only, but can leave comments  groupsAccesses: {    viewer: ["*:read", "comments:write"],  },
  // `userId: "marc"` has full write access  usersAccesses: {    "marc@example.com": ["*:write"],  },});

Note that groupIds and userId are set when authenticating a user.

More information

A user’s access to a room is defined by a list of permissions.

Each permission uses the format resource:scope. The resource can be * for the whole room, with read or write scope. Specific resources such as storage, comments, and feeds can use read, write, or none.

Base permissions

By setting the permission for the resource *, you define the base scope for all the resources of the room. You can choose between read or write access:

• *:read → the user will have read access to everything in the room.
• *:write → the user will have write access to everything in the room.

More granular permissions

You can opt into or opt out of access to specific room resources:

• Storage with storage:read, storage:write, or storage:none.
• Comments with comments:read, comments:write, or comments:none.
• Public threads with comments:public:read, comments:public:write, or comments:public:none.
• Private threads with comments:private:read, comments:private:write, or comments:private:none.
• Feeds with feeds:read, feeds:write, or feeds:none.

The comments:* permissions apply to public and private threads. Use comments:public:* and comments:private:* to override one visibility.

Here’s an example giving write access to everything except read-only access to storage:

[  "*:write",  "storage:read", // Lower storage access from write to read];

Here’s an example giving read access to everything, except write access to comments and no access to feeds:

[  "*:read",  "comments:write", // Raise comments access to write  "feeds:none", // Remove access to feeds];

Here’s an example giving write access to public threads, but no access to private threads:

[  "*:write",  "comments:private:none", // Remove access to private threads];

Public and private threads

By default, threads are visible to all users that have permission to read the room, but they can be marked as private by passing visibility: "private" when the thread is created. Users then need private comments permissions to create or read private threads. For more information, read how to add private commenting to your app, or find a summary of the APIs under public and private threads.

Where to use permissions

With ID tokens, use permissions in defaultAccesses, groupsAccesses, and usersAccesses when you create or update rooms. With access tokens, use permissions when you allow access to rooms in an authentication endpoint.