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. To create additional Role Sets with different combinations of Roles, you'll need the Enhanced Organizations add-on⁠.

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 Roles & Permissions⁠.
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.

Create a Role Set

To create additional Role Sets beyond the Primary Role Set, you'll need the Enhanced Organizations add-on⁠.

To create a Role Set:

1. In the Clerk Dashboard, navigate to Roles & Permissions⁠.
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⁠ 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.
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⁠.
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. 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 Roles & Permissions⁠.
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.
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:

• Create Roles and Permissions to include in Role Sets
• Check access based on Roles and Permissions
• Invite members to Organizations