---
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/authentication/id-token) and
[Access Token](/docs/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/authentication/id-token).

#### 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", 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](/docs/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).