Roles and permissions

Clerk supports modeling your own custom role and permissions to control access to resources within your application when you use organizations.

Roles

Roles determine a user's level of access to the organization. You can extend a role's privileges and access to resources by adding permissions.

Default roles

For each instance, there are currently two default roles:

• Admin (org:admin) - Offers full access to organization resources. Members with the admin role have all the System Permissions. They can fully manage the organization and organization memberships.
• Member (org:member) - Offers limited access to organization resources. Access to organization resources is limited to the "Read members" permission only, by default. They cannot manage the organization and organization memberships, but they can view information about other members in it.

The Creator role

When a user creates a new organization, they're automatically added as its first member and assigned the organization's designated Creator role. By default, that role is org:admin.

You cannot delete an organization role if it's used as the organization's Creator role. But, you can reassign the Creator role to any other role with the right permissions. For example, if you want to delete the admin role, you will have to assign another role as the Creator role.

The Creator role must at least have the following System Permissions:

• Manage members (org:sys_memberships:manage)
• Read members (org:sys_memberships:read)
• Delete organization (org:sys_profile:delete)

To reassign the Creator role:

1. In the Clerk Dashboard, navigate to Roles⁠.
2. Create a new role or use an existing role from the list.
3. Ensure that Manage members, Read members, and Delete organization system permissions are selected for the role.
4. Open the three dots icon for the role.
5. From the dropdown, select the Set as Creator role option.

The Default role for members

New organization members are initially assigned the Default role. By default, that role is org:member. This role is used as a pre-filled default in <OrganizationProfile /> invitations and for organization enrollment with verified domains.

You cannot delete an organization role if it's used as the organization's Default role. But, you can reassign the Default role to any other role.

To reassign the Default role:

1. In the Clerk Dashboard, navigate to Roles⁠.
2. Create a new role or use an existing role from the list.
3. Open the three dots icon for the role.
4. From the dropdown, select the Set as Default role option.

Custom roles

You can create up to 10 custom organization roles per application instance to meet your application needs. If you need more than 10 roles, contact support⁠.

Custom roles can be granted permissions and access. For example, you can create a new role of Billing (org:billing) which can be used to group users who belong to a specific department of the organization and have permission to manage credit card information, invoices, and other resources related to billing.

To create a new role:

1. In the Clerk Dashboard, navigate to Roles⁠
2. Select Create new role.
3. Give the role a name, a key to reference it by in the format org:<role>, and a description.
4. Select Create role.

Change a user's role

You can change a user's role in the Clerk Dashboard, or in your application, such as in the <OrganizationSwitcher /> component.

To change a user's role in the Clerk Dashboard:

1. In the top in the Clerk Dashboard, select Organizations⁠ and select an organization.
2. Select the Members tab.
3. In the list of members, find the one whose role you want to change.
4. Select another role from their role dropdown.

Delete a role

You cannot delete a role that is still assigned to members of an organization. Change the members to a different role before completing the following steps.

1. In the Clerk Dashboard, navigate to Roles⁠.
2. Select the three dots icon next to the role.
3. Select Delete role.

Permissions

Permissions grant users privileged access to resources and operations, like creating and deleting. Clerk supports two types of permissions: System and Custom.

System permissions

Clerk provides a set of system permissions that power Clerk's Frontend API⁠ and organization-related Clerk components. These permissions serve as the baseline required for Clerk to operate effectively.

Clerk's system permissions consist of the following:

• Manage organization (org:sys_profile:manage)
• Delete organization (org:sys_profile:delete)
• Read members (org:sys_memberships:read)
• Manage members (org:sys_memberships:manage)
• Read domains (org:sys_domains:read)
• Manage domains (org:sys_domains:manage)
• Read billing (org:sys_billing:read)
• Manage billing (org:sys_billing:manage)

You can assign these system permissions to any role.

Custom permissions

When creating a new permission, follow the format org:<feature>:<permission>. You can then assign the permission to an existing role.

For example, you could create a new permission called Create invoices (org:invoices:create) which allows only users with this permission to edit invoices. Then, you could assign this permission to a role, or multiple roles, such as Billing (org:billing) or Sales (org:sales).

To create a new permission:

1. In the Clerk Dashboard, navigate to Permissions⁠.
2. Select Create new permission.
3. Give the permission a name, a key to reference it by in the format org:<feature>:<permission>, and a description.
   Note

   Common permission values could be:

   • create — to allow creating resources
   • read — to allow reading/viewing resources
   • update/manage — to allow updating/editing resources
   • delete — to allow deleting resources

   For example, you could create a new permission called Create invoices (org:invoices:create) which allows only users with this permission to edit invoices. Then, you could assign this permission to a role, or multiple roles, such as Billing (org:billing) or Sales (org:sales).

4. Select Create permission.

Verify a user's role or permission

It's best practice to always verify whether or not a user is authorized to access sensitive information, important content, or exclusive features. Authorization is the process of determining the access rights and privileges of a user, ensuring they have the necessary permissions to perform specific actions. To perform authorization checks using a user's role or permission, see the guide on authorizing users.

Next steps

• Learn how to limit access to content or entire routes based on a user's role or permissions
• Learn how to automatically invite users to an organization based on their email domain
• Learn how to manually invite users to an organization
• Learn how to automatically add users to an organization based on their email domain