Skills

Chapter 9 of 22

Clerk Orgs

Clerk Organizations for B2B SaaS - create multi-tenant apps with org switching, role-based access, verified domains, and enterprise SSO.

6 minutes · 1,243 words · 31 sections

Organizations (B2B SaaS)

Clerk Orgs · clerk/skills · Skills Docs

Task	Reference
System permissions catalog, custom roles, role sets	references/roles-permissions.md
Invitation lifecycle (create, list, revoke, built-in UI)	references/invitations.md
Enterprise SSO setup, provider field access, domain verification	references/enterprise-sso.md
Next.js adaptations for orgs (role/permission middleware, slug invariants, orgId-scoped writes)	references/nextjs-patterns.md

Reference	Description
`references/roles-permissions.md`	Default + custom roles, System Permissions catalog, permission naming
`references/invitations.md`	Backend API for invitations + built-in UI
`references/enterprise-sso.md`	SAML/OIDC per-org, domain verification, correct field access
`references/nextjs-patterns.md`	Next.js adaptations specific to orgs. For generic Next.js patterns see `clerk-nextjs-patterns` skill.

Action	URL
Enable Organizations + Membership mode	`https://dashboard.clerk.com/last-active?path=organizations-settings`
Manage roles + permissions	`https://dashboard.clerk.com/last-active?path=organizations-settings/roles`
Create/edit an organization	`https://dashboard.clerk.com/last-active?path=organizations`
Webhooks for org events	`https://dashboard.clerk.com/last-active?path=webhooks`

clerk api --platform PATCH /v1/platform/applications/<app_id>/instances/<ins_id>/config \
  -d '{"organization_settings":{"max_allowed_memberships":50,"domains_enabled":true,"admin_delete_enabled":true}}'

# Create:
clerk api -X POST /v1/organizations \
  -d '{"name":"Acme","slug":"acme","created_by":"user_xxx","max_allowed_memberships":10}'

# List:
clerk api /v1/organizations --query 'limit=20'

# Get one:
clerk api /v1/organizations/<org_id>

# Update:
clerk api -X PATCH /v1/organizations/<org_id> -d '{"name":"Acme Inc."}'

# Delete:
clerk api -X DELETE /v1/organizations/<org_id>

# Add a user to an org:
clerk api -X POST /v1/organizations/<org_id>/memberships \
  -d '{"user_id":"user_xxx","role":"org:admin"}'

# List members:
clerk api /v1/organizations/<org_id>/memberships --query 'limit=50'

# Update role:
clerk api -X PATCH /v1/organizations/<org_id>/memberships/<user_id> \
  -d '{"role":"org:member"}'

# Remove:
clerk api -X DELETE /v1/organizations/<org_id>/memberships/<user_id>

# Send:
clerk api -X POST /v1/organizations/<org_id>/invitations \
  -d '{"email_address":"alice@example.com","role":"org:member","redirect_url":"https://app.com/accept"}'

# List pending:
clerk api /v1/organizations/<org_id>/invitations --query 'status=pending'

# Revoke:
clerk api -X POST /v1/organizations/<org_id>/invitations/<inv_id>/revoke \
  -d '{"requesting_user_id":"user_xxx"}'

import { auth } from '@clerk/nextjs/server'

const { orgId, orgSlug, orgRole } = await auth()
if (!orgId) {
  // user has no active org — either not in any, or viewing Personal Account
}

export default async function OrgPage({ params }: { params: { slug: string } }) {
  const { orgSlug } = await auth()
  if (orgSlug !== params.slug) {
    redirect('/dashboard')  // or whatever your "no-access" flow is
  }
  return <div>Welcome to {orgSlug}</div>
}

import { OrganizationSwitcher } from '@clerk/nextjs'

<OrganizationSwitcher
  hidePersonal
  afterCreateOrganizationUrl="/orgs/:slug/dashboard"
  afterSelectOrganizationUrl="/orgs/:slug/dashboard"
/>

// app/session-tasks/choose-organization/page.tsx
import { TaskChooseOrganization } from '@clerk/nextjs'

export default function Page() {
  return <TaskChooseOrganization redirectUrlComplete="/dashboard" />
}

Role	Default meaning
`org:admin`	Full access — all System Permissions, can manage org + memberships
`org:member`	Read members + Read billing Permissions only

const clerk = await clerkClient()
await clerk.organizations.createOrganization({
  name: 'Acme Corp',
  createdBy: userId,
  maxAllowedMemberships: 10,
})

// Update later:
await clerk.organizations.updateOrganization(orgId, {
  maxAllowedMemberships: 25,
})

const org = await clerk.organizations.getOrganization({ organizationId: orgId })
await clerk.organizations.updateOrganization(orgId, {
  publicMetadata: { ...org.publicMetadata, newField: 'value' },
})

Error / symptom	Root cause	Fix
`orgId` / `orgSlug` is `undefined` for a signed-in user	Organizations not enabled for this instance, OR user has no active org (personal account)	Enable in Dashboard → Organizations; check Membership mode; surface `<OrganizationSwitcher />`
`has({ permission: 'org:manage_members' })` always `false`	Using an invented permission slug	Use `org:sys_memberships:manage` (see roles-permissions.md catalog)
`has({ role })` returns `false` but user looks like an admin	Session token stale after role change	Re-sign-in, or refresh the session: `await clerk.session?.reload()`
`has({ permission })` `false` even with the role assigned	Feature not attached to active Plan (Billing gates permissions)	Dashboard → Billing → Plans → attach Feature
`<OrganizationSwitcher />` doesn’t show “Personal Account”	`Membership required` mode is on (the default since Aug 22, 2025)	Dashboard → Organizations settings → `Membership optional`
`TaskChooseOrganization` throws “cannot render when a user doesn’t have current session tasks”	Rendered outside a `choose-organization` task context	Wrap in a `choose-organization` session-task route only; don’t render unconditionally
`enterpriseAccounts[0].provider` is `undefined`	Accessing `provider` at the wrong nesting level	Use `user.enterpriseAccounts[0].enterpriseConnection?.provider`

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()

  if (orgSlug !== params.slug) redirect('/dashboard')
  if (!has({ role: 'org:admin' })) redirect(`/orgs/${orgSlug}`)

  return <div>Admin settings for {orgSlug}</div>
}

import { clerkClient, auth } from '@clerk/nextjs/server'

export async function inviteMember(organizationId: string, emailAddress: string, role: string) {
  const { userId, has } = await auth()

  if (!userId) throw new Error('Not signed in')
  if (!has({ permission: 'org:sys_memberships:manage' })) {
    throw new Error('Not authorized to invite members')
  }

  const clerk = await clerkClient()
  return clerk.organizations.createOrganizationInvitation({
    organizationId,
    inviterUserId: userId,       // required per Backend API
    emailAddress,
    role,                        // e.g. 'org:admin' or 'org:member'
    redirectUrl: 'https://yourapp.com/accept-invite',
  })
}

Colophon for this issue

Colophon

How this issue was made

Source

github.com/clerk/skills, branch main, last pushed 6 August 2026.

Licence

Discovery

22 chapters found by walking the repository tree for SKILL.md, not by matching a directory convention. 5 distinct layouts observed: .agents/skills/*/SKILL.md, skills/core/*/SKILL.md, skills/features/*/SKILL.md, skills/frameworks/*/SKILL.md, skills/mobile/*/SKILL.md.

Issue colours

Resolved from the owner’s published design.md — hue 284°, chroma 0.190. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.

Typefaces

Display: Suisse Intl is not available to us; set in Inter.
Body: Suisse Intl is not available to us; set in Inter.
Mono: Söhne Mono is not available to us; set in JetBrains Mono.

We never load a typeface at request time from a third-party origin, so a brand face we do not already self-host is substituted rather than fetched.

Heading repairs

1 repair applied to this chapter so the document has one h1 and no skipped levels:

Shifted “31 headings” from h1 to h2 so the chapter title is the only h1.

Spec compliance

Every chapter satisfies the Agent Skills specification’s frontmatter rules.

Images

Images inside a chapter come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.

Marketplace

A plugin manifest is published at .claude-plugin/marketplace.json by Clerk, declaring 4 plugins. It is read for editorial metadata only — never as the skill index, which is always the repository tree.

Signal

Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.

Agent surfaces

The whole issue is available as one markdown document at /clerk/skills.md, and each chapter at its own .md URL.

Publication

Set by Skills Docs from the source repository. Body text is Literata at the reader’s chosen size and measure; code is Geist Mono. Nothing on this page was written by us except this paragraph.

Appendix 9.1–9.5

ReferencesMarkdown · 4 files

Also bundledJSON · 1 file

About this skill

Trigger

Colophon

Appendix 9.1–9.5

ReferencesMarkdown · 4 files

Also bundledJSON · 1 file