Authentication - Tenants

Tenants allows you to compartmentalize Liveblocks resources, such as inbox notifications, rooms, and everything associated with rooms such as threads, text editors, Yjs, Storage. Each tenant represents a separate organization or customer in your system, meaning you can easily add a workspace/org switcher to your application, with each workspace having its own notification inbox.

Setting up tenants

To set up Tenants, you just need to set a tenantId when creating a resource, for example, when creating a room.

const room = await liveblocks.createRoom("my-room-id", {  tenantId: "my-tenant-id",});

Resources using tenants

A number of Liveblocks resources use tenants, such as rooms, comments, text editors, Yjs, Storage, inbox notifications, mention groups.

const { data: rooms, nextCursor } = await liveblocks.getRooms({  tenantId: "my-tenant-id",});
await liveblocks.triggerInboxNotification({  userId: "steven@example.com",  kind: "$fileUploaded",  subjectId: "my-file",  activityData: {},  tenantId: "my-tenant-id",});
await liveblocks.deleteAllInboxNotifications({  userId: "steven@example.com",  tenantId: "my-tenant-id",});
const { data, nextCursor } = await liveblocks.getUserRoomSubscriptionSettings({  userId: "steven@example.com",  tenantId: "my-tenant-id",});

Above you can see getRooms, triggerInboxNotification, deleteAllInboxNotifications and getUserRoomSubscriptionSettings using tenants. Tenants can also be used with the REST API.

Authentication

When authorizing a user with Liveblocks, you can specify the tenant they belong to. Each user is only authorized for one tenant at a time, meaning they need to re-authenticate to access resources in another tenant, such as notifications. Tenants can be used with both Access Token and ID Token authentication.

With access tokens

When using access tokens, you can set the tenantId when you prepare a session. Tokens generated for a specific tenant, will only allow access to resources inside this tenant, even if the token has permissions to rooms in other tenants.

const session = liveblocks.prepareSession("olivier@example.com", {  tenantId: "tenant123",});
// Giving full access to one roomsession.allow("Vu78Rt:design:9Hdu73", session.FULL_ACCESS);
// Give full access to every room with an ID beginning with "Vu78Rt:product:"session.allow("Vu78Rt:product:*", session.FULL_ACCESS);
const { body, status } = await session.authorize();

Learn more about access tokens.

With ID tokens

When using ID tokens, you can set the tenantId when using identifyUser. Tokens generated for a specific tenant, will only allow 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);

Learn more about ID tokens.

Switching tenants

The easiest way to switch tenants is to refresh the page, for example with location.reload(), then pass a new tenantId to your chosen authentication method.