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.
If you enabled organizations for your application before December 2023, the Admin role is admin and the Member role is basic_member, instead of org:admin and org:member, respectively.
Custom role
You can create up to 10 custom organization roles per application instance to meet your application needs. If you need more than 10 roles, reach out to support@clerk.dev.
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.
The Creator role
When a user creates a new organization, that user is automatically added as the organization's first member and is assigned the Creator role. By default, Admin (org:admin) is the Creator role.
You can't delete a role if it's used as the organization's Creator role. However, you can reassign the Creator role to another 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 has a set of System Permissions that power Clerk’s Frontend API(opens in a new tab) and organization-related Clerk Components. They are a baseline set of permissions that Clerk needs to operate functionally.
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)
You can assign these System Permissions to any role.
Custom permissions
When creating a new permission, follow the format org:<resource>:<action>. You can then assign the permission to an existing role.
For example, you could create a new role called Sales (org:sales) and a new permission called Create invoices (org:invoices:create) which allows only users with this permission to edit invoices. You could also grant this permission to the Billing role.