Clerk orgs: set up RBAC end to end, roles, permissions, then enforce

TL;DR: Organizations plus roles plus permissions plus an authorization check is one pipeline, not four separate configs. Skip a step and the permissions silently do nothing. Enable organizations first (Configure, then Organizations in the dashboard). Open the Roles and Permissions page.

Clerk orgs RBAC end to end

Roles and permissions only work as a chain: org enabled, role set defined, roles created, permissions attached to features and roles, members assigned, code checks. Break any link and authorization fails open or silently grants nothing.

The order

1. Enable organizations first (Configure, then Organizations in the dashboard). Role sets, roles, and permissions all hang off orgs. Defining roles before this leaves them unattached.

2. Open the Roles and Permissions page. Each organization gets a Role Set that decides which roles can be assigned to its members. Start from the default set before inventing custom ones.

3. Create custom roles only when admin and member are not enough. Limit: up to 10 custom roles per instance. Each gets a name, a key (final form org:rolekey), a description, and a choice of whether it joins the default Role Set.

4. Create a Feature first, then custom permissions under it. Permission keys follow org:feature:permission. Permissions attach to roles, never directly to users.

5. Assign roles to members (Organizations, pick the org, Members tab, role dropdown) or through the backend API.

6. Enforce in code. On the client use has() for permission checks; on the server check auth() for org role or permission. A role nobody checks is decoration.

The traps

• String-comparing the org role to "admin" breaks the day you add a custom role. Check permissions with has() instead of comparing role names.

• The default member role only carries read members and read billing system permissions. It cannot manage the org. If members need more, that is a new role or new permissions, not a tweak to member.

• System permissions like org:sys_memberships:manage power Clerk's own components. Do not assume a custom role with zero system permissions can drive the organization profile components.

When to use this

• This covers exactly what the title says: Clerk orgs.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with Clerk; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

Compatibility

• Not pinned to a specific version; follows current Clerk behavior.

Verified live against the Clerk docs 2026-09-26 at https://clerk.com/docs/guides/organizations/roles-permissions. Roles are assigned through role sets, custom roles cap at 10 per instance, permission keys follow org:feature:permission, and the member role only has read members and read billing system permissions by default.