# Role Sets

> This feature requires a [paid plan](https://clerk.com/pricing){{ target: '_blank' }} for production use, but all features are free to use in development mode so that you can try out what works for you. See the [pricing](https://clerk.com/pricing){{ target: '_blank' }} page for more information.

Role Sets are collections of available [Roles](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions.md) you can assign to members in an Organization. This lets you control role availability on a per-organization basis - if a Role isn't in an Organization's Role Set, members of that Organization can't be assigned to that Role.

When you create an Organization, it's automatically assigned to the **Default Role Set**. By default, this is set to Clerk's **Primary Role Set**, which includes the `admin` and `member` Roles. The Primary Role Set is free and can be modified to fit your needs. To create additional Role Sets with different combinations of Roles, you'll need the [**Enhanced B2B Authentication** add-on](https://clerk.com/pricing){{ target: '_blank' }}.

When you modify a Role Set, the changes are automatically applied to all Organizations using it. This makes it easy to roll out new Roles across multiple Organizations at once.

## When to use Role Sets

Use Role Sets when different Organizations need different available Roles. This works well for:

- **Different pricing tiers** - Your Free plan offers only `admin` and `member`, Pro adds `moderator` and `analyst`, and Enterprise adds `security_admin` and `compliance_officer`.
- **Different customer cohorts** - Small practices get `physician` and `nurse`, while large hospitals also get `department_head` and `specialist`. All cohorts share `admin` and `member`, but get additional Roles specific to their size.

If all Organizations need the same custom Roles, just modify the Primary Role Set instead. Refer to [Roles and Permissions](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions.md) to learn how.

## Primary Role Set

The **Primary Role Set** is Clerk's default Role Set. It includes:

- **Admin (`org:admin`)** - Full access to Organization resources and management
- **Member (`org:member`)** - Limited access to Organization resources

You can add or remove Roles from it. If you remove a Role that members have, you'll go through the [remapping flow](#remapping-flow).

## Default Role Set

The **Default Role Set** determines which Role Set is automatically assigned to new Organizations. By default, this is configured to use the Primary Role Set, but you can change it to any other Role Set you've created.

To configure the Default Role Set:

1. In the Clerk Dashboard, navigate to [**Roles & Permissions**](https://dashboard.clerk.com/~/organizations-settings/roles).
2. Select the three dots next to the Role Set you want to set as default.
3. From the dropdown, select the **Set as default role set** option.
4. Confirm your changes.

> This only affects new Organizations. Existing Organizations keep their current Role Set unless you manually change them.

## Create a Role Set

To create additional Role Sets beyond the Primary Role Set, you'll need the [**Enhanced B2B Authentication** add-on](https://clerk.com/pricing){{ target: '_blank' }}.

To create a Role Set:

1. In the Clerk Dashboard, navigate to [**Roles & Permissions**](https://dashboard.clerk.com/~/organizations-settings/roles).
2. Select **Create role set**.
3. Give the Role Set a name, a key to reference it by, and a description.
4. Under **Roles**, click **Add Roles**. You can select from a list of global Roles or create new ones. You must also select a **Organization creator role** and a **New member default role**.
5. Select **Save**.

## Assign a Role Set to an Organization

You can assign a different Role Set to an organization to change which Roles are available to its members.

To assign a Role Set:

1. Navigate to [**Organizations**](https://dashboard.clerk.com/~/organizations) in the Clerk Dashboard and select an Organization.
2. Select the **Settings** tab.
3. Under **Roles**, you'll see the current Role Set (the Primary Role Set by default).
4. Choose a new Role Set from the dropdown.
5. If members have Roles that don't exist in the new set, you'll go through the [remapping flow](#remapping-flow).
6. Select **Confirm**.

## Edit a Role Set

When you edit a Role Set, the changes are automatically applied to all Organizations using it.

To edit a Role Set:

1. In the Clerk Dashboard, navigate to [**Roles & Permissions**](https://dashboard.clerk.com/~/organizations-settings/roles).
2. Select the Role Set you want to edit.

To add Roles, click **Add Roles**. You can select from a list of global Roles or create new ones. You must also select a **Organization creator role** and a **New member default role**.

To remove Roles, click on the three dots next to a Role and select **Remove role**. Confirm this change by typing the role name and clicking **Next**. If you remove a Role that members have, you will go through the [remapping flow](#remapping-flow). If you delete a default Role, the reassigned Role will be the new default Role.

> Removing a Role affects **all Organizations** using that Role Set. To remove a Role from just one Organization, create a new Role Set for it instead.

## Delete a Role Set

To delete a Role Set:

1. In the Clerk Dashboard, navigate to [**Roles & Permissions**](https://dashboard.clerk.com/~/organizations-settings/roles).
2. Select the **Role sets** tab.
3. Select the three dots next to the Role Set.
4. Select **Delete role set**.
5. If Organizations are using this Role Set, you'll be prompted to select a replacement Role Set for them. You will go through the [remapping flow](#remapping-flow).
6. Confirm by typing the Role Set key.

## Remapping flow

If you modify a Role that members have, you'll be prompted to select a replacement Role. This happens when you:

- Change an Organization's Role Set to one that doesn't include all current Roles.
- Remove a Role from a Role Set that members have.
- Delete a Role Set assigned to an Organization. Once you select a replacement Role Set, Clerk will prompt you to select replacement Roles.

**Example:**

Your Organization uses the "Basic Role Set" with `admin`, `member`, and `viewer`. You switch to the "Advanced Role Set" with `admin`, `member`, `moderator`, and `analyst`.

Since `viewer` doesn't exist in Advanced, you need to remap those members:

1. Select which Role they should receive (e.g., `member`).
2. Click **Remap roles** to confirm and Clerk will remap `viewer` members to `members`.

## Next steps

Now that you've learned about Role Sets, you can:

- [Set up Roles and Permissions](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions.md): Learn how to create Roles and Permissions to include in Role Sets.
- [Check access](https://clerk.com/docs/guides/organizations/control-access/check-access.md): Learn how to check access based on Roles and Permissions.
- [Add members to your Organization](https://clerk.com/docs/guides/organizations/add-members/invitations.md): Learn how to add members to your Organization with invitations.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)