Docs

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.

Note

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, 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 learn more about creating custom roles, see the Create roles and permissions guide.

The Default role for members

The Default role for members is the role that users are initially assigned as a new organization member. Initially, this role is the Member (org:member) role. This is the role that is used as a pre-filled default for invitations in <OrganizationProfile /> and for organization enrollment with verified domains.

Warning

You can't delete a role if it's used as the organization's Default role. However, you can reassign the Default role to another role.

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.

Warning

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

Warning

System permissions are not included in session claims. To do permission-checks on the server-side, you must create custom permissions.

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

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on