āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/organizations/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 determine a user's level of access to the organization. You can extend a role's privileges and access to resources by adding permissions.
For each instance, there are currently two default roles:
org:admin) - Offers full access to organization resources. Members with the admin role have all of the system permissions. They can fully manage the organization and organization memberships.org:member) - Offers limited access to organization resources. Access to organization resources is limited to the "Read members" and "Read billing" permissions only, by default. They cannot manage the organization and organization memberships, but they can view information about other members in it.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:
org:sys_memberships:manage)org:sys_memberships:read)org:sys_profile:delete)To reassign the Creator role:
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:
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{{ target: '_blank' }}.
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:
org:<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:
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.
Permissions grant users privileged access to resources and operations, like creating and deleting. Clerk supports two types of permissions: system permissions and custom permissions.
Clerk provides a set of system permissions that power Clerk's Frontend API{{ target: '_blank' }} 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:
org:sys_profile:manage)org:sys_profile:delete)org:sys_memberships:read)org:sys_memberships:manage)org:sys_domains:read)org:sys_domains:manage)org:sys_billing:read)org:sys_billing:manage)You can assign these system permissions to any role.
[!WARNING] System permissions aren't included in session claims. To check permissions on the server-side, you must create custom permissions.
Custom permissions let you define fine-tuned access control within your organization. Each permission is tied to a feature, and can be assigned to one or more roles. To create a custom permission, you must first create a role (e.g. sales) and a feature within that role (e.g. invoices). Once both exist, you can define specific permissions (e.g. create) related to that feature.
To create a new permission:
org:<feature>:<permission>.
[!NOTE] Common permission values could be:
createā to allow creating resourcesreadā to allow reading/viewing resourcesupdate/manageā to allow updating/editing resourcesdeleteā to allow deleting resourcesFor 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).
You can also create a custom permission by navigating to the Features tab in the Clerk Dashboard.
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.
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā