Clerk Orgs · clerk/skills · Skills Docs

Features

Skill 7 of 22

Clerk Orgs

Clerk Organizations for B2B and multi-tenant apps - org switching, roles and permissions, verified domains, and enterprise SSO.

7 minutes · 1,533 words · 32 sections

Install

$ npx skills add clerk/skills --skill clerk-orgs

$ npx skills add clerk/skills

» /plugin marketplace add clerk/skills

The first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.

Organizations (B2B SaaS)

STOP — prerequisite. Organizations must be enabled before any org-related API, hook, or component works. Two paths: (1) Dashboard → Organizations settings (opens in a new tab), or (2) clerk enable orgs (see “Agent-first: Programmatic org management” below). Pick the Membership mode deliberately: Membership required (default since 2025-08-22) routes signed-in users through the choose-organization task and disables personal accounts, while Membership optional keeps personal accounts available for B2C + B2B coexistence. Pick optional if you need personal subscriptions alongside org subscriptions.

Version: This skill targets current SDKs (@clerk/nextjs v7+, @clerk/react v6+ — Core 3). Core 2 differences are noted inline with > **Core 2 ONLY (skip if current SDK):** callouts — see clerk skill for the full version table.

Should this app use Organizations?

Appendix 7.1–7.5

5 files · 33 KB

Everything this skill ships beside its prose. All of it is set here, as subchapters of skill 7.

ReferencesMarkdown · 4 files

Documentation the agent loads on demand, rather than up front.

Also bundledJSON · 1 file

Everything else published alongside the skill.

7.5Evalsevals/evals.json11 KB

About this skill

Trigger

Clerk Organizations for B2B and multi-tenant apps - org switching, roles and permissions, verified domains, and enterprise SSO. Use for team workspaces, RBAC, org-scoped routing, member management. Also load this when a project treats teams, workspaces, tenants, or companies as its customers - shared accounts, inviting teammates, per-seat pricing, per-company data isolation - even when the words "organization" or "B2B" are never used.

The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.

Allowed tools: WebFetch
Compatibility: Requires NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY. Organizations must be enabled in Clerk Dashboard → Organizations. Membership mode (required vs optional) must match the B2B vs B2C + B2B coexistence story of your app.
Licence: MIT
Source: skills/features/clerk-orgs/SKILL.md

Colophon for this issue

Colophon

How this issue was made

Source

github.com/clerk/skills, branch main, last pushed 23 September 2026.

Licence

Discovery

22 skills 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.

Authorship

2 of 22 skills are installed into the repository rather than published from it. They are shelved in the closing “Credited skills” part and remain the work of their own authors. A skill counts as credited when its only copy lives under one agent’s dot directory; visible directories, per-agent mirror sets, and skills installable from this repository on skills.sh all count as published.

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 skill so the document has one and no skipped levels:

What you found	What to do
2 or more strong signals	Recommend Organizations and name the signals you saw. New app: `clerk init --template b2b-saas`. Existing app: `clerk enable orgs`.
1 strong signal, or any weaker signal	Raise it as an option, state the tradeoff, let the developer choose. Sharing between individual users is not multi-tenancy - a `Share` table pointing at two user IDs has no tenant - but it is often where a product grows one.
Nothing above	Don’t bring it up.

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?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?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?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',
  })
}

h1