Skip to Content
You are viewing a beta version of Clerk Docs
Visit the latest docs
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com

Verify the active user's permissions in an organization

The following authorization checks are predicated on a user having an active organization. Without this, they will likely always evaluate to false by default. Clerk's built-in <OrganizationSwitcher/> component anduseOrganizationList().setActive({ organization: <orgId> }) method are two available options to set an organization as active for a user.

In general, you should always verify whether or not a user is authorized to access sensitive information, important content, or exclusive features. The most secure way to implement authorization is by checking the active user's role or permissions.

Clerk enables two broad approaches to role and permissions-based authorization:

  1. Immediately blocking unauthorized users.
  • Use the <Protect> component to prevent content from rendering if the active user is unauthorized.
  • Call auth().protect() to throw an error if the active user is unauthorized.
  1. *Configuring custom behavior for unauthorized users.
  • The has() helper returns false if the active user lacks the role or permissions you're checking for. You can choose how your app responds without immediately throwing an error or preventing content from rendering.

Authorization in Client Components

The examples below work for both SSR and CSR. Examples are written for Next.js App Router but they are supported by any React meta framework, such as Remix or Gatsby.

The following snippet uses Clerk's <Protect> component to only render the form for users with the org:team_settings:manage permission.

/app/dashboard/settings/form.tsx
'use client'; import { Protect } from "@clerk/nextjs"; export function SettingsForm(){ return ( <Protect permission="org:team_settings:manage" fallback={<p>You are not allowed to see this section.</p>} > <form> .... </form> </Protect> ) }

Authorization in React Server Components

The following example uses has() to inspect a user's permissions granularly. If the user doesn't have the org:team_settings:read permission, the component returns null instead of rendering its children.

/app/dashboard/settings/layout.tsx
import type { PropsWithChildren } from "react"; import { auth } from "@clerk/nextjs/server"; export default function SettingsLayout(props: PropsWithChildren){ const { has } = auth() const canAccessSettings = has({permission: "org:team_settings:read"}); if(!canAccessSettings) return null; return props.children }

Authorization in endpoints

import { auth } from "@clerk/nextjs/server"; export default function ServerComponent() { async function myAction() { 'use server' const { has } = auth(); const canManage = has({permission:"org:team_settings:manage"}); ... // Perform a DB operation ... } }

Authorization in Remix Loaders

export const loader: LoaderFunction = async args => { const { has } = await getAuth(args); if(has({permission: "org:team_settings:manage"})){ return redirect('/request-access'); } return {}; }; export default function Settings() { return ( <div> <h1>Settings Page</h1> </div> ); }

Authorization in JS SDK

If you are not using React or any of the meta-frameworks we support, there's a good chance that you are using Clerk.js directly. In that case, the following example can help.

import Clerk from '@clerk/clerk-js' const clerk = new Clerk(...) await clerk.load(...) const canManageSettings = clerk.session.checkAuthorization({ permission: "org:team_settings:manage" })

Authorize with roles

Performing role checks is not considered a best-practice and developers should avoid it as much as possible. Usually, complex role checks can be refactored with a single permission check.

You can pass a role the same way you can pass a permission in all the examples above.

The following example uses <Protect>'s condition prop to conditionally render its children if the user is either an org:admin or an org:billing_manager.

/app/dashboard/settings/layout.tsx
import type { PropsWithChildren } from "react"; import { Protect } from "@clerk/nextjs"; export default function SettingsLayout(props: PropsWithChildren){ return ( <Protect condition={has => has({role: "org:admin"}) || has({role: "org:billing_manager"})} > {props.children} </Protect> ) }

How to add types for roles and permissions

In order to enhance typesafety in your project, you can define a global ClerkAuthorization interface, which defines the acceptable values for roles and permissions.

By default, types related to roles and permissions, such as OrganizationCustomRoleKey and OrganizationCustomPermissionKey, will be assigned to string if ClerkAuthorization is not defined. If you define ClerkAuthorization in your project, OrganizationCustomRoleKey and OrganizationCustomPermissionKey will be assigned to the keys of the ClerkAuthorization interface.

In the example below, ClerkAuthorization is defined with the default roles that Clerk provides.

types/globals.d.ts
export { }; declare global { interface ClerkAuthorization { permission: ''; role: 'org:admin' | 'org:member'; } }

Because Clerk supports custom roles and permissions, you can modify ClerkAuthorization to align with the roles and permissions configured in your Clerk application. See how in the example below, the default Clerk roles org:admin and org:member are replaced with custom roles org:super_admin, org:teacher, and org:student.

types/globals.d.ts
export { }; declare global { interface ClerkAuthorization { permission: 'org:quiz:create' | 'org:quiz:grade' | 'org:quiz:read' | 'org:quiz:fill'; role: 'org:super_admin' | 'org:teacher' | 'org:student'; } }

Last updated on March 1, 2024

What did you think of this content?

Clerk © 2024