---
meta:
  title: "Organizations"
  parentTitle: "Authentication"
  description: "Learn more about organizations"
---

Organizations allow you to compartmentalize Liveblocks resources, such as inbox
notifications, rooms, and everything associated with rooms such as comment
threads, realtime data stored, and more. Each organization 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.

<Banner title="Using organizations is optional">

If you don't specify an organization, no configuration is needed. By default,
resources belong to the `default` organization ID.

</Banner>

<Figure>
  <Image
    src="/assets/organizations/concept-organizations.png"
    alt="Concept of organizations"
    width={1494}
    height={840}
    quality={100}
  />
</Figure>

### Setting up organizations

To set up Organizations, you just need to set a `organizationId` when creating a
resource, for example, when creating a room.

```ts
const room = await liveblocks.createRoom("my-room-id", {
  // +++
  organizationId: "my-organization-id",
  // +++
});
```

<Banner title="You can't change a resource's organization" type="warning">

It's not possible to change a resource's `organizationId` after creation. You
will need to migrate the resource into a new room in the correct organization.

</Banner>

#### Resources using organizations

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

```ts
const { data: rooms, nextCursor } = await liveblocks.getRooms({
  // +++
  organizationId: "my-organization-id",
  // +++
});

await liveblocks.triggerInboxNotification({
  userId: "steven@example.com",
  kind: "$fileUploaded",
  subjectId: "my-file",
  activityData: {},
  // +++
  organizationId: "my-organization-id",
  // +++
});

await liveblocks.deleteAllInboxNotifications({
  userId: "steven@example.com",
  // +++
  organizationId: "my-organization-id",
  // +++
});

const { data, nextCursor } = await liveblocks.getUserRoomSubscriptionSettings({
  userId: "steven@example.com",
  // +++
  organizationId: "my-organization-id",
  // +++
});
```

Above you can see [`getRooms`](/docs/api-reference/liveblocks-node#get-rooms),
[`triggerInboxNotification`](/docs/api-reference/liveblocks-node#post-inbox-notifications-trigger),
[`deleteAllInboxNotifications`](/docs/api-reference/liveblocks-node#delete-users-userId-inboxNotifications)
and
[`getUserRoomSubscriptionSettings`](/docs/api-reference/liveblocks-node#get-users-userId-room-subscription-settings)
using organizations. Organizations can also be used with the
[REST API](/docs/api-reference/rest-api-endpoints).

### Authentication

When authorizing a user with Liveblocks, you can specify the organization they
belong to. Each user is only authorized for one organization at a time, meaning
they need to re-authenticate to access resources in another organization, such
as notifications. Organizations can be used with both
[ID Token](/docs/api-reference/authentication#id-token) and
[Access Token](/docs/api-reference/authentication/access-token) authentication.

#### With ID tokens

When using ID tokens, you can set the `organizationId` when using
`identifyUser`. Tokens generated for a specific organization, will only allow
access to resources inside this organization, even if the user has access to
rooms in other organizations.

```ts highlight="3"
const { body, status } = await liveblocks.identifyUser({
  userId: "olivier@example.com",
  organizationId: "organization123",
});

// '{ token: "eyJga7..." }'
console.log(body);
```

Learn more about
[ID tokens](/docs/api-reference/authentication#id-token-workspace-permissions).

#### With access tokens

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

```ts highlight="2"
const session = liveblocks.prepareSession("olivier@example.com", {
  organizationId: "organization123",
});

// Giving full access to one room
session.allow("Vu78Rt:design:9Hdu73", ["*:write"]);

// Give full access to every room with an ID beginning with "Vu78Rt:product:"
session.allow("Vu78Rt:product:*", ["*:write"]);

const { body, status } = await session.authorize();
```

Learn more about
[access tokens](/docs/api-reference/authentication/access-token).

#### Switching organizations

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

---

For an overview of all available documentation, see [/llms.txt](/llms.txt).