Check Roles and Permissions with Authorization Checks
Authorization checks are checks you perform in your code to determine the access rights and privileges of a user, ensuring they have the necessary Permissions to perform specific actions or access certain content. These checks are essential for protecting sensitive data, gating premium features, and ensuring users stay within their allowed scope of access.
Within Organizations, authorization checks can be performed by checking a user's Roles or Custom Permissions. Roles like org:admin determine a user's level of access within an Organization, while Custom Permissions like org:invoices:create provide fine-grained control over specific features and actions.
Examples
You can protect content and even entire routes based on Organization membership, Roles, and Permissions by performing .
In the following example, the page is restricted to authenticated users, users who have the org:admin Role, and users who belong to the Acme Corp Organization. It uses the has() helper to perform the authorization check for the org:admin Role.
import { auth, clerkClient } from '@clerk/nextjs/server'
export default async function Page() {
// Use `auth()` to access the `Auth` object
// https://clerk.com/docs/reference/backend/types/auth-object
const { isAuthenticated, orgId, has } = await auth()
// Check if the user is authenticated
if (!isAuthenticated) return <p>You must be signed in to access this page.</p>
// Check if there is an Active Organization
if (!orgId) return <p>Set an Active Organization to access this page.</p>
// Check if the user has the `org:admin` Role
if (!has({ role: 'org:admin' })) return <p>You must be an admin to access this page.</p>
// Initialize clerkClient
const client = await clerkClient()
// Use the `getOrganization()` method to get the Backend `Organization` object
const organization = await client.organizations.getOrganization({ organizationId: orgId })
// Check if Organization name matches (e.g., 'Acme Corp')
const requiredOrgName = 'Acme Corp'
if (organization.name !== requiredOrgName)
return (
<p>
This page is only accessible in the <strong>{requiredOrgName}</strong> Organization. Switch
to the <strong>{requiredOrgName}</strong> Organization to access this page.
</p>
)
return (
<p>
You are currently signed in as an <strong>admin</strong> in the{' '}
<strong>{organization.name}</strong> Organization.
</p>
)
}'use client'
import { useAuth, useOrganization } from '@clerk/nextjs'
export default function Page() {
// The `useAuth()` hook gives you access to properties like `isSignedIn` and `has()`
const { isSignedIn, has } = useAuth()
const { organization } = useOrganization()
const requiredOrgName = 'Acme Corp'
// Check if the user is authenticated
if (!isSignedIn) return <p>You must be signed in to access this page.</p>
// Check if there is an Active Organization
if (!organization) return <p>Set an Active Organization to access this page.</p>
// Check if the user has the `org:admin` Role
if (!has({ role: 'org:admin' })) return <p>You must be an admin to access this page.</p>
// Check if Organization name matches (e.g., 'Acme Corp')
if (organization.name !== requiredOrgName)
return (
<p>
This page is only accessible in the <strong>{requiredOrgName}</strong> Organization. Switch
to the <strong>{requiredOrgName}</strong> Organization to access this page.
</p>
)
return (
<p>
You are currently signed in as an <strong>admin</strong> in the{' '}
<strong>{organization.name}</strong> Organization.
</p>
)
}When a user isn't in the required Organization, render an <OrganizationSwitcher /> alongside the message to let them switch to the required Organization.
For more examples on how to perform authorization checks, see the dedicated guide.
Next steps
Now that you know how to check Roles and Permissions, you can:
Perform authorization checks
Learn how to perform authorization checks to limit access to content or entire routes based on a user's Role or Permissions.
Features and Plans
Learn how to check Features and Plans for Subscription-based applications.
Set up Roles and Permissions
Learn how to set up Roles and Permissions to control what invited users can access.
Configure default Roles
Learn how to configure default Roles for new Organization members.
Feedback
Last updated on