Role Sets

Role Sets are collections of available Roles 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, or you can create additional Role Sets with different combinations of Roles.

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 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.

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 the Roles & Permissions⁠ page.
2. Open the three-dot menu 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.

Create a Role Set

To create a Role Set:

1. In the Clerk Dashboard, navigate to the Roles & Permissions⁠ page.
2. Select Create role set.
3. Give the Role Set a name, a key to reference it by, and a description.
4. Under Roles, select Add roles. You can select from a list of global Roles or create new ones. You must also select an Organization creator role and a New members 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. In the Clerk Dashboard, navigate to the Organizations⁠ page 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. Select 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.
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 the Roles & Permissions⁠ page.
2. Select the Role Set you want to edit.

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

To remove Roles, open the three-dot menu next to a Role and select Remove role. Confirm this change by typing the Role name and selecting Next. If you remove a Role that members have, you will go through the remapping flow. If you delete a default Role, the reassigned Role will be the new default Role.

Delete a Role Set

To delete a Role Set:

1. In the Clerk Dashboard, navigate to the Roles & Permissions⁠ page.
2. Select the Role sets tab.
3. Open the three-dot menu 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.
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. Select Remap roles to confirm and Clerk will remap viewer members to member.

Next steps

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