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.

To learn more about creating custom roles, see the Create roles and permissions guide.

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.

To learn more about creating custom permissions, see the Create roles and permissions guide.

Next steps

Last updated on March 28, 2024