Organizations (B2B SaaS)
Prerequisite: Enable Organizations in Clerk Dashboard first.
Quick Start
- •Create an organization via dashboard or through Clerk API
- •Use OrganizationSwitcher to let users switch between orgs
- •Protect routes using orgSlug from URL and role checks
Documentation Reference
Key Patterns
1. Get Organization from Auth
Server-side access to organization:
typescript
import { auth } from '@clerk/nextjs/server'
const { orgId, orgSlug } = await auth()
console.log(`Current org: ${orgSlug}`)
2. Dynamic Routes with Org Slug
Create routes that accept org slug:
code
app/orgs/[slug]/page.tsx app/orgs/[slug]/settings/page.tsx
Access the slug:
typescript
export default function DashboardPage({ params }: { params: { slug: string } }) {
return <div>Organization: {params.slug}</div>
}
3. Check Organization Membership
Verify user has access to specific org:
typescript
import { auth } from '@clerk/nextjs/server'
export default async function ProtectedPage() {
const { orgId, orgSlug } = await auth()
if (!orgId) {
return <div>Not in an organization</div>
}
return <div>Welcome to {orgSlug}</div>
}
4. Role-Based Access Control
Check if user has specific role:
typescript
const { has } = await auth()
if (!has({ role: 'org:admin' })) {
return <div>Admin access required</div>
}
5. OrganizationSwitcher Component
Let users switch between organizations:
typescript
import { OrganizationSwitcher } from '@clerk/nextjs'
export default function Nav() {
return (
<header>
<h1>Dashboard</h1>
<OrganizationSwitcher />
</header>
)
}
Default Roles
All new members get assigned a role:
| Role | Permissions |
|---|---|
org:admin | Full access, manage members, settings |
org:member | Limited access, read-only |
Custom roles can be created in the dashboard.
Default Permissions
| Permission | Role |
|---|---|
org:create | Can create new organizations |
org:manage_members | Can invite/remove members (default: admin) |
org:manage_roles | Can change member roles (default: admin) |
org:update_metadata | Can update org metadata (default: admin) |
Authorization Pattern
Complete example protecting a route:
typescript
import { auth } from '@clerk/nextjs/server'
import { redirect } from 'next/navigation'
export default async function AdminPage({ params }: { params: { slug: string } }) {
const { orgSlug, has } = await auth()
// Verify user is in the org
if (orgSlug !== params.slug) {
redirect('/dashboard')
}
// Check if admin
if (!has({ role: 'org:admin' })) {
redirect(`/orgs/${orgSlug}`)
}
return <div>Admin settings for {orgSlug}</div>
}
Common Pitfalls
| Symptom | Cause | Solution |
|---|---|---|
orgSlug is undefined | Not calling await auth() | Use const { orgSlug } = await auth() |
| Role check always fails | Not awaiting auth() | Add await before auth() |
| Users can access other orgs | Not checking orgSlug matches URL | Verify orgSlug === params.slug |
| Org not appearing in switcher | Organizations not enabled | Enable in Clerk Dashboard → Organizations |
| Invitations not working | Wrong role configuration | Ensure members have invite role permissions |
Workflow
- •Setup - Enable Organizations in Clerk Dashboard
- •Create org - Users create org or admin creates via API
- •Add members - Send invitations or add directly
- •Assign roles - Default member role, promote to admin as needed
- •Build protected routes - Use auth() to check orgSlug and roles
- •Use OrganizationSwitcher - Let users switch between orgs