diff --git a/docs/_partials/organization-sync-options.mdx b/docs/_partials/organization-sync-options.mdx index 1dc9e50a29..29af69fe07 100644 --- a/docs/_partials/organization-sync-options.mdx +++ b/docs/_partials/organization-sync-options.mdx @@ -26,7 +26,7 @@ object has the type `OrganizationSyncOptions`, which has the following propertie - `personalAccountPatterns` - [Pattern](#pattern)\[] - URL patterns for resources that exist within the context of a user's [personal account](/docs/guides/organizations/overview#allow-personal-accounts). + URL patterns for resources that exist within the context of a user's [personal account](/docs/guides/organizations/configure#enable-organizations). If the route also matches the `organizationPattern` prop, the `organizationPattern` prop takes precedence. diff --git a/docs/guides/configure/session-tasks.mdx b/docs/guides/configure/session-tasks.mdx index 9efcba40a6..1f1952a6ef 100644 --- a/docs/guides/configure/session-tasks.mdx +++ b/docs/guides/configure/session-tasks.mdx @@ -35,7 +35,7 @@ The following table lists the available tasks and their corresponding components | Name | Component | | - | - | -| [Personal accounts disabled (default)](/docs/guides/organizations/overview#allow-personal-accounts) | [``](/docs/reference/components/authentication/task-choose-organization) | +| [Personal accounts disabled (default)](/docs/guides/organizations/configure#enable-organizations) | [``](/docs/reference/components/authentication/task-choose-organization) | > [!IMPORTANT] > Personal accounts being disabled by default was released on 08-22-2025. Applications created before this date will not be able to see the **Allow personal accounts** setting, because personal accounts were enabled by default. @@ -286,7 +286,7 @@ The `useAuth()` hook and helpers that access the [`auth` object](/docs/reference ##### Example: Personal accounts disabled -When organizations are enabled, [personal accounts are disabled by default](/docs/guides/organizations/overview#allow-personal-accounts) and your users will be required to select or create an organization after authenticating. Until completed, their session remains `pending`. Pages that are protected using Clerk's protection utilities will treat the user's session as signed-out. +When organizations are enabled, [personal accounts are disabled by default](/docs/guides/organizations/configure#enable-organizations) and your users will be required to select or create an organization after authenticating. Until completed, their session remains `pending`. Pages that are protected using Clerk's protection utilities will treat the user's session as signed-out. For `useAuth()`, `isSignedIn` will be `false` and `userId` and `orgId` will be `null` if the user has a `pending` session. diff --git a/docs/guides/development/custom-flows/organizations/manage-user-org-invitations.mdx b/docs/guides/development/custom-flows/organizations/manage-user-org-invitations.mdx index a20547d9a7..2e1767f445 100644 --- a/docs/guides/development/custom-flows/organizations/manage-user-org-invitations.mdx +++ b/docs/guides/development/custom-flows/organizations/manage-user-org-invitations.mdx @@ -5,7 +5,7 @@ description: Learn how to use the Clerk API to build a custom flow for managing -This guide will demonstrate how to use the Clerk API to build a custom flow for managing a user's [organization invitations](/docs/guides/organizations/overview#organization-invitations). +This guide will demonstrate how to use the Clerk API to build a custom flow for managing a user's [organization invitations](/docs/guides/organizations/invitations). diff --git a/docs/guides/organizations/check-access.mdx b/docs/guides/organizations/check-access.mdx new file mode 100644 index 0000000000..1c7c6ed941 --- /dev/null +++ b/docs/guides/organizations/check-access.mdx @@ -0,0 +1,90 @@ +--- +title: Check roles and permissions with authorization checks +description: Limit access to content or entire routes based on a user's organization role or permissions. +metadata: + title: Check roles and permissions in organizations +--- + +Authorization checks verify that users can only access resources and perform actions they have permission for within an organization. These checks are essential for protecting sensitive data, gating premium features, and ensuring users stay within their allowed scope of access. + +Clerk provides two primary ways to perform these checks: the `has()` method for server-side logic and the `` component for conditional rendering in React. Both methods let you check against roles, permissions, features, and plans. + +## What you can check + +Authorization checks can verify roles and 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. + +> [!IMPORTANT] +> Clerk links custom permissions to features. A permission check for `org:invoices:create` will only return `true` if the organization's active plan includes the `invoices` feature **and** the user has the permission. Learn more in the [roles and permissions guide](/docs/guides/organizations/roles-and-permissions#custom-permissions). + +## Frontend checks with `` + +The `` component is the easiest way to conditionally show or hide content in React applications based on what a user can access. This works well for UI elements like buttons, sections, or entire page layouts that should only appear to users with specific access. You can show or hide content based on roles and permissions, render different layouts for different access levels, or display fallback messages when access is denied. + +Use the `` component to conditionally render content based on role or permission: + +```tsx +import { Protect } from '@clerk/nextjs' + +export default function Dashboard() { + return ( +
+

Dashboard

+ + {/* Only show to org admins */} + + + + + {/* Only show to users with specific permission */} + + + + + {/* Display fallback when access is denied */} + You don't have access to reports.

}> + + +
+ ) +} +``` + +## Server-side checks with `has()` + +While `` works well for the frontend, server-side checks are essential for securing API routes, backend logic, and data access. The `has()` method provides a way to verify access before performing sensitive operations or returning protected data. You'll use this when protecting API endpoints, controlling database operations, validating permissions before executing business logic, or returning different data based on user access. + +Use the `has()` method from the `auth()` object to check permissions on the server: + +```tsx +import { auth } from '@clerk/nextjs/server' + +export default async function handler(req, res) { + const { has, userId } = await auth() + + if (!userId) { + return res.status(401).json({ error: 'Unauthorized' }) + } + + // Check if user has admin role + if (!has({ role: 'org:admin' })) { + return res.status(403).json({ error: 'Forbidden' }) + } + + // Check if user has specific permission + if (!has({ permission: 'org:invoices:create' })) { + return res.status(403).json({ error: 'Forbidden' }) + } + + // Proceed with authorized action + // ... +} +``` + +## Next steps + +Now that you know how to check roles and permissions, you can: + +- [Read the complete authorization checks guide](/docs/guides/secure/authorization-checks) for advanced patterns including middleware protection and custom authorization logic +- [Learn how to check features and plans](/docs/guides/billing/for-b2b#control-access-with-features-plans-and-permissions) for subscription-based applications +- [Set up custom roles and permissions](/docs/guides/organizations/roles-and-permissions) to define your access control model +- [Configure default roles](/docs/guides/organizations/configure#default-roles) for new organization members diff --git a/docs/guides/organizations/configure.mdx b/docs/guides/organizations/configure.mdx new file mode 100644 index 0000000000..1f84d9d975 --- /dev/null +++ b/docs/guides/organizations/configure.mdx @@ -0,0 +1,166 @@ +--- +title: Configure organizations +description: Learn how to configure global organization settings in the Clerk Dashboard, including pricing, membership limits, and optional features. +metadata: + title: Configure organization settings in Clerk Dashboard +--- + +Global organization settings control how organizations work across your entire application. These settings determine who can create organizations, how members join them, what roles they receive, and which features are available. You'll configure most of these when you first enable organizations, though you can adjust them later as your needs evolve. + +## Enable organizations + +Organizations are disabled by default. When you enable organizations, Clerk offers two workspace models: + +- **Personal accounts disabled (default)**: Every user is required to belong to an organization. All new and existing users will be prompted to create or join an organization through the [session tasks flow](/docs/guides/configure/session-tasks) before they can access your application. + + > [!IMPORTANT] + > Personal accounts being disabled by default was released on August 22, 2025. Applications created before this date will not see the **Allow personal accounts** setting, because personal accounts were enabled by default. + +- **Personal accounts enabled**: Users can operate in their own individual workspace or join organizations. They start in their personal account and can switch to organizations using the [``](/docs/reference/components/organization/organization-switcher) component. + +Most B2B and multi-tenant applications leave personal accounts disabled. This ensures proper data isolation and team structure from the start. You should only enable personal accounts if your app serves both individual users and teams (like a tool that works for solo users but also has team features). + +To enable organizations: + +1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page. +1. Select **Enable Organizations**. +1. In the modal, toggle **Allow personal accounts** based on your decision above. +1. Select **Enable**. + +Clerk measures organizations by Monthly Active Organizations (MAOs). Refer to the [overview page](/docs/guides/organizations/overview#how-do-organizations-work) for pricing details and limits. + +## Organization settings + +Once organizations are enabled, you can configure core features and behaviors, such as membership limits, verified domains, organization slugs, and whether to allow personal accounts alongside organizations. + +### Membership limits + +There is no limit to the number of organizations a user can be a member of. + +Each organization allows a maximum of 5 members by default. You can increase this limit as your customer base grows, or set different limits for individual organizations if you have different pricing tiers. + +To change the membership limit for all organizations in your application: + +1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page. +1. In the **Default membership limit** section, update the membership limit. + - **Free plan**: Allows a maximum of 5 members in an organization + - **Pro plan**: Allows unlimited members in an organization + +To change the membership limit for a specific organization: + +1. In the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/~/organizations). +1. Select the organization you want to update. +1. In the **Membership limit** section, update the limit for that specific organization. + +### Allow personal accounts + +When enabling the organizations feature, you were prompted to choose whether to allow personal accounts. This setting is disabled by default. Refer to the [section on enabling organizations](#enable-organizations) above for a detailed explanation of how personal accounts work. + +You can change this setting after initial setup, which is useful if your product strategy evolves. For example, if you initially served only teams but now want to support individual users as well. + +To change this setting: + +1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page. +1. Toggle **Allow personal accounts**. + +### Verified domains + +Verified domains allow automatic or suggested organization membership for users with specific email domains (like `@acme.com`). This is useful for company-wide rollouts where you want to streamline enrollment for employees with company email addresses. Members with the [`org:sys_domains:manage` system permission](/docs/guides/organizations/roles-and-permissions#system-permissions) can manage verified domains and enrollment modes. + +Learn more about [verified domains](/docs/guides/organizations/verified-domains). + +### Organization slugs + +> [!IMPORTANT] +> Organization slugs are disabled by default for applications created after October 7, 2025. For applications created before this date, you can opt to disable it. + +Organization slugs are human-readable URL identifiers (like `acme-corp`) that help users reference which organization they're working in. Enable this feature if you need organization-specific URLs or if users frequently switch between multiple organizations. + +You can also [use organization slugs in your application's URLs](/docs/guides/organizations/org-slugs-in-urls). + +### Allow user-created organizations + +By default, users can create organizations in your application. You can restrict this if you prefer to manually provision organizations. + +You can also override this permission for specific users in their profile page under **User permissions**. + +Learn more about [creating organizations](/docs/guides/organizations/create-and-manage). + +#### Organization creation limit + +{/* TODO: Come back to this. Is the max 100, or is it unlimited? By default, in the Clerk Dash, it says unlimited. But I thought Clerk caps each user to create up to 100 orgs per application instance */} + +When user-created organizations are enabled, each user can create up to 100 organizations by default. You can configure this to set a lower limit or allow unlimited organizations. + +To change the default limit: + +1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page. +1. In the **Organization limit** section, choose between: + - **Users can create unlimited organizations** + - **Users can create a limited number of organizations** (specify the limit) + +If you need users to create more than 100 organizations, [contact support](/contact/support){{ target: '_blank' }} to have the limit raised. + +To override this limit for a specific user: + +1. In the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/~/users). +1. Select the user you want to update. +1. In the **User permissions** section, configure their organization creation limit. + +### Default roles + +When users create or join organizations, they need to be assigned a role. These settings determine which roles are automatically assigned in different scenarios, whether someone is creating a new organization or joining an existing one. + +#### Default role for members + +The default role for members is assigned to users when they join an organization through invitations or verified domain enrollment. By default, this is set to [**Member**](/docs/guides/organizations/roles-and-permissions#default-roles). + +This role is used: + +- When sending invitations from the [``](/docs/reference/components/organization/organization-profile) component (pre-filled as default) +- When users auto-join via [verified domains](/docs/guides/organizations/verified-domains) +- As the suggested role for new organization members + +To change the default role: + +1. In the Clerk Dashboard, navigate to the [**Roles & Permissions**](https://dashboard.clerk.com/~/organizations-settings/roles) page. +1. Select the three dots next to the role you want to set as default. +1. Choose **Set as Default role**. + +Learn more about [roles and permissions](/docs/guides/organizations/roles-and-permissions). + +#### Creator's initial role + +When a user creates a new organization, Clerk automatically adds them as its first member and assigns them the organization's designated **Creator** role. By default, that role is [**Admin**](/docs/guides/organizations/roles-and-permissions#default-roles), giving them full control over the organization they created. + +The Creator role must have at least these [system permissions](/docs/guides/organizations/roles-and-permissions#system-permissions): + +- Manage members (`org:sys_memberships:manage`) +- Read members (`org:sys_memberships:read`) +- Delete organization (`org:sys_profile:delete`) + +Learn more about the [Creator role and how to reassign it](/docs/guides/organizations/roles-and-permissions#the-creator-role). + +### Allow new members to delete organizations + +This setting controls whether organization members can delete organizations. + +By default, any member with the [`org:sys_profile:delete` system permission](/docs/guides/organizations/roles-and-permissions#system-permissions) can delete an organization. You can disable this if you want to prevent accidental data loss or require your own approval process before organizations are removed. + +To change this setting: + +1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page. +1. Toggle **Allow new members to delete organizations**. + +> [!IMPORTANT] +> This setting only applies to newly created organizations. Existing organizations retain their current deletion settings. + +Learn more about [roles and permissions](/docs/guides/organizations/roles-and-permissions). + +## Next steps + +Now that you've configured global settings, you can: + +- [Create your first organization](/docs/guides/organizations/create-and-manage) and start adding members +- [Add members to your organization](/docs/guides/organizations/invitations) with invitations, verified domains, or SSO +- [Configure access control](/docs/guides/organizations/roles-and-permissions) with custom roles and permissions diff --git a/docs/guides/organizations/create-and-manage.mdx b/docs/guides/organizations/create-and-manage.mdx new file mode 100644 index 0000000000..74ae485efc --- /dev/null +++ b/docs/guides/organizations/create-and-manage.mdx @@ -0,0 +1,61 @@ +--- +title: Create and manage organizations +description: Learn how to create and manage individual organizations in the Clerk Dashboard and in your application. +metadata: + title: Create and manage Organizations with Clerk +--- + +Organizations can be created and managed either **in the Clerk Dashboard** or **in your application**. This guide covers working with individual organizations. For global settings that affect all organizations in your application (like enabling organizations, setting default roles, or configuring memberships), refer to the [dedicated guide](/docs/guides/organizations/configure). + +## Create an organization + +Organizations can be created in the Clerk Dashboard or in your application. The number of organizations you can create depends on your [Monthly Active Organization (MAO) limits](/docs/guides/organizations/overview#how-do-organizations-work). + +### Create an organization in the Clerk Dashboard + +To create an organization in the Clerk Dashboard, navigate to the [**Organizations**](https://dashboard.clerk.com/~/organizations) page and select the **Create Organization** button. + +### Create an organization in your application + +By default, [users have permission to create organizations within your application](/docs/guides/organizations/configure#allow-user-created-organizations). When a user creates an organization, they become the organization's [admin](/docs/guides/organizations/roles-and-permissions#default-roles) with full control over settings, members, and permissions. + +**Default limits**: Each user can create up to 100 organizations. To change creation permissions or limits, see the [dedicated guide](/docs/guides/organizations/configure#allow-user-created-organizations). + +The easiest way to allow users to create organizations is to use the [``](/docs/reference/components/organization/create-organization) and/or [``](/docs/reference/components/organization/organization-switcher) components. The `` component is more comprehensive, as it handles all organization flows including creation, switching, and management. + +If the prebuilt components don't meet your needs, you can build [custom flows](/docs/guides/development/custom-flows/overview) using the Clerk API. + +## Manage organizations + +As an application owner, you can manage all organizations in your application, both those created by you and those created by your users. You can view, update, and delete any organization, as well as manage its members and settings. + +### Manage organizations in the Clerk Dashboard + +To manage an organization in the Clerk Dashboard, navigate to the [**Organizations**](https://dashboard.clerk.com/~/organizations) page. Select a specific organization to view its details, members, invitations, subscriptions, payments, and settings. + +### Manage organizations in your application + +For managing organizations in your application, Clerk provides prebuilt components that handle organization management flows: + +- [``](/docs/reference/components/organization/organization-profile) - A profile page for the user's currently active organization where they can update settings and manage members. +- [``](/docs/reference/components/organization/organization-switcher) - A dropdown menu that handles all organization flows, including switching between organizations and managing the active organization's profile. +- [``](/docs/reference/components/organization/organization-list) - A list of organizations that a user is a member of, with options to switch between them. + +If the prebuilt components don't meet your needs, you can build [custom flows](/docs/guides/development/custom-flows/overview) using the Clerk API. + +## Switch between organizations + +Users who belong to multiple organizations can switch between them at any time. The currently selected organization is called the active organization. + +The [``](/docs/reference/components/organization/organization-switcher) component provides the easiest way for users to switch between organizations. If you need more control over the switching logic, you can use the `setActive()` method from the [`useOrganizationList()`](/docs/reference/hooks/use-organization-list) hook, or access it directly from the [`Clerk`](/docs/reference/javascript/clerk#set-active) object. + +If [personal accounts are enabled](/docs/guides/organizations/configure#allow-personal-accounts), users can also switch to their personal account using the `` component. + +## Next steps + +Now that you know how to create and manage organizations, you can: + +- [Add custom data with organization metadata](/docs/guides/organizations/metadata) +- [Use organization slugs in URLs](/docs/guides/organizations/org-slugs-in-urls) for tenant-specific routing +- [Invite members to organizations](/docs/guides/organizations/invitations) +- [Set up roles and permissions](/docs/guides/organizations/roles-and-permissions) diff --git a/docs/guides/organizations/invitations.mdx b/docs/guides/organizations/invitations.mdx index 3136e774df..50e2d2cb50 100644 --- a/docs/guides/organizations/invitations.mdx +++ b/docs/guides/organizations/invitations.mdx @@ -1,18 +1,28 @@ --- title: Invite users to your organization -description: Step-by-step guide on how to send, manage, and track user invitations within your multitenant SaaS, all using Clerk Organizations. +description: Send, manage, and track user invitations within your multi-tenant SaaS using Clerk organizations. metadata: - title: Send and manage B2C/B2B organization invitations via Clerk + title: Send and manage organization invitations via Clerk --- -Organization invitations allow you to add new members to your organization. When you send an invitation, Clerk sends an email to the invited user with a unique invitation link. When the user visits the organization invitation link, they will be redirected to the [Account Portal sign-in page](/docs/guides/customizing-clerk/account-portal#sign-in). If the user is already signed in, they will be redirected to your application's homepage (`/`). If you want to redirect the user to a specific page in your application, you can [specify a redirect URL when creating the invitation](#redirect-url). +Organization invitations let you add new members to your organization. When you send an invitation, Clerk sends an email to the invited user with a unique invitation link. When the user visits the organization invitation link, Clerk redirects them to the [Account Portal sign-in page](/docs/guides/customizing-clerk/account-portal#sign-in). If the user is already signed in, Clerk redirects them to your application's homepage (`/`). If you want to redirect the user to a specific page in your application, you can [specify a redirect URL when creating the invitation](#redirect-url). -By default, only admins can invite users to an organization. +By default, only [admins](/docs/guides/organizations/roles-and-permissions#default-roles) can invite users to an organization. This feature requires that [**Email** is enabled](/docs/guides/configure/auth-strategies/sign-up-sign-in-options#email), as Clerk uses the user's email address to send the invitation. You can still disable **Email** as a sign-in option if you do not want users to be able to sign-in with their email address. To configure your application's **Email** settings, navigate to the [**User & authentication**](https://dashboard.clerk.com/~/user-authentication/user-and-authentication) page in the Clerk Dashboard. +## When to use invitations + +Invitations work well when you need precise control over who joins your organization and which role they receive. This approach fits scenarios where: + +- Teams are small and members are known in advance. +- Onboarding requires manual approval or review. +- Specific roles need to be assigned during the invitation. + +If you want to streamline enrollment for users with company email addresses, consider [verified domains](/docs/guides/organizations/verified-domains), which can automatically invite users based on their email domain. If customers require centralized authentication through their Identity Provider, use [enterprise SSO](/docs/guides/organizations/sso). + ## Create an invitation Clerk's [prebuilt components](/docs/reference/components/overview) and [Account Portal pages](/docs/guides/customizing-clerk/account-portal) manage all organization invitation flows, including creating, managing, and accepting invitations. @@ -21,7 +31,7 @@ However, if you want to build custom flows, see the following sections. ### Client-side -To create an organization invitation on the client-side, see the [dedicated guide](/docs/guides/development/custom-flows/organizations/manage-organization-invitations). Note that this uses the [`organizations.inviteMember()`](/docs/reference/javascript/organization#invite-member) method, which does not allow you to specify a redirect URL; it will always redirect to the Account Portal sign-in page. If you want to specify a redirect URL, you must create the invitation on the server-side. +To create an organization invitation on the client-side, see the [dedicated guide](/docs/guides/development/custom-flows/organizations/manage-organization-invitations). Note that this uses the [`organizations.inviteMember()`](/docs/reference/javascript/organization#invite-member) method, which does not let you specify a redirect URL; it will always redirect to the Account Portal sign-in page. If you want to specify a redirect URL, you must create the invitation on the server-side. ### Server-side @@ -83,11 +93,11 @@ Once the user visits the invitation link, they will be redirected to the page yo > [!TIP] > -> - To test redirect URLs in your development environment, pass your port. For example, `http://localhost:3000/accept-invitation`. +> To test redirect URLs in your development environment, pass your port. For example, `http://localhost:3000/accept-invitation`. ### Invitation metadata -You can also add metadata to an invitation when creating the invitation through the Backend API. Once the invited user signs up using the invitation link, the **invitation** metadata (`OrganizationInvitation.publicMetadata`) will be stored in the organization **membership's** metadata (`OrganizationMembership.publicMetadata`). You can find more information about organization membership metadata in the [Organization Membership](/docs/reference/javascript/types/organization-membership) docs. +You can also add metadata to an invitation when creating the invitation through the Backend API. Once the invited user signs up using the invitation link, Clerk stores the **invitation** metadata (`OrganizationInvitation.publicMetadata`) in the organization **membership's** metadata (`OrganizationMembership.publicMetadata`). For more details on organization membership metadata, see the [OrganizationMembership](/docs/reference/javascript/types/organization-membership) reference. To add metadata to an invitation, add the `public_metadata` parameter when creating the invitation. @@ -144,3 +154,12 @@ Use the following tabs to see examples for each method. To use the JS Backend SDK to revoke an organization invitation, see the [`revokeOrganizationInvitation()`](/docs/reference/backend/organization/revoke-organization-invitation) reference documentation. + +## Next steps + +Now that you know how to invite users to your organization, you can: + +- [Configure verified domains](/docs/guides/organizations/verified-domains) to automatically invite users based on their email domain +- [Set up enterprise SSO](/docs/guides/organizations/sso) for centralized authentication through an Identity Provider +- [Set up roles and permissions](/docs/guides/organizations/roles-and-permissions) to control what invited users can access +- [Add metadata to invitations](/docs/guides/organizations/metadata) for tracking or custom workflows diff --git a/docs/guides/organizations/metadata.mdx b/docs/guides/organizations/metadata.mdx index 49f1cfd541..120e8579e8 100644 --- a/docs/guides/organizations/metadata.mdx +++ b/docs/guides/organizations/metadata.mdx @@ -5,33 +5,52 @@ metadata: title: Custom metadata for B2B authentication flows --- -Organization metadata allows you to store information about an organization that is not part of the standard fields, such as custom attributes that are specific to your application. +Organization metadata lets you store custom information about an organization that is not part of the standard fields, such as custom attributes that are specific to your application. This is useful for advanced user segmentation, analytics, or storing application-specific data like subscription tier, department, or region. -There are two types of metadata: **public** and **private**. +Metadata is stored on the [`Organization`](/docs/reference/javascript/organization) and [`OrganizationMembership`](/docs/reference/javascript/types/organization-membership) objects. -- Both **public** and **private** metadata are set and can be accessed from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. -- Only **public** metadata can be accessed from the [Frontend API](/docs/reference/frontend-api/){{ target: '_blank' }}. +## Types of metadata -Both the `Organization` and `Organization Membership` objects have the metadata fields: `publicMetadata` and `privateMetadata`. +There are two types of organization metadata: **public** and **private**. + +| Metadata | Frontend API | Backend API | +| - | - | - | +| Public | Read access | Read & write access | +| Private | No read or write access | Read & write access | + +Both the [`Organization`](/docs/reference/javascript/organization) and [`OrganizationMembership`](/docs/reference/javascript/types/organization-membership) objects have the metadata fields: `publicMetadata` and `privateMetadata`. - Use the `publicMetadata` property if you need to set some metadata from your backend and have them displayed as read-only on the frontend. - Use the `privateMetadata` property if the custom attributes contain sensitive information that should not be displayed on the frontend. ## Set organization metadata -There are two ways to set organization metadata: +You can set organization metadata in the [Clerk Dashboard](https://dashboard.clerk.com/~/organizations) or using Clerk's Backend API. See the [`updateOrganizationMetadata()`](/docs/reference/backend/organization/update-organization-metadata) and [`updateOrganizationMembershipMetadata()`](/docs/reference/backend/organization/update-organization-membership-metadata) methods for more information. + +## Access public metadata + +To access public metadata on the frontend, it's available on the [`Organization`](/docs/reference/javascript/organization) object, which can be accessed using the [`useOrganization()`](/docs/reference/hooks/use-organization) hook. + +To access public metadata on the backend, it's available on the [Backend `Organization`](/docs/reference/backend/types/backend-organization) object which can be accessed using the [`getOrganization()`](/docs/reference/backend/organization/get-organization) method. This method will return the `Organization` object which contains the public metadata. However, this method is subject to [rate limits](/docs/guides/how-clerk-works/system-limits#backend-api-requests), so _if you are accessing the metadata frequently_, it's recommended to [attach it to the user's session token](#metadata-in-the-session-token). + +## Metadata in the session token + +Retrieving metadata from the `Organization` or `OrganizationMembership` objects on the server-side requires making an API request to Clerk's Backend API, which is slower and is subject to [rate limits](/docs/guides/how-clerk-works/system-limits#backend-api-requests). You can store it in the user's session token, which doesn't require making an API request as it's available on the user's authentication context. **However, there is a size limitation to keep in mind.** Clerk stores the session token in a cookie, and most browsers cap cookie size at [**4KB**](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). After accounting for the size of Clerk's default claims, the cookie can support **up to 1.2KB** of custom claims. **Exceeding this limit will cause the cookie to not be set, which will break your app as Clerk depends on cookies to work properly.** + +If you need to store more than 1.2KB of metadata, you should [store the extra data in your own database](/docs/guides/development/webhooks/syncing#storing-extra-user-data) instead. If this isn't an option, you can [move particularly large claims out of the token](/docs/guides/sessions/session-tokens#example) and fetch them using a separate API call from your backend, but this approach brings back the issue of making an API request to Clerk's Backend API, which is slower and is subject to rate limits. -- In the Clerk Dashboard -- Using the [JS Backend SDK](/docs/js-backend/getting-started/quickstart) +Another limitation of storing metadata in the session token is that when you modify metadata server-side, the changes won't appear in the session token until the next refresh. To avoid race conditions, either [force a JWT refresh](/docs/guides/sessions/force-token-refresh) after metadata changes or handle the delay in your application logic. -### In the Clerk Dashboard +If you've considered the limitations, and you still want to store metadata in the session token: -1. In the Clerk Dashboard, navigate to the [**Organizations**](https://dashboard.clerk.com/~/organizations) page. -1. Select the organization you want to update. -1. In the **Organization metadata** section, select **Edit** next to the metadata you want to update. +1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/~/sessions) page. +1. Under **Customize session token**, in the **Claims** editor, you can add any claim to your session token that you need and select **Save**. To avoid exceeding the session token's 1.2KB limit, it's not recommended to add the entire `organization.public_metadata` or `organization_membership.public_metadata` object. Instead, add individual fields as claims, like `organization.public_metadata.birthday`. When doing this, it's recommended to leave particularly large claims out of the token to avoid exceeding the session token's size limit. See the [example](/docs/guides/sessions/session-tokens#example) for more information. -### Using the JS Backend SDK +## Next steps -To ease the flow of setting metadata, Clerk provides the [`updateOrganizationMetadata()`](/docs/reference/backend/organization/update-organization-metadata) and [`updateOrganizationMembershipMetadata()`](/docs/reference/backend/organization/update-organization-membership-metadata) methods from the [JS Backend](/docs/js-backend/getting-started/quickstart), which is a wrapper around the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}. +Now that you understand organization metadata, you can: - +- [Use organization slugs in URLs](/docs/guides/organizations/org-slugs-in-urls) for tenant-specific routing +- [Add metadata to invitations](/docs/guides/organizations/invitations#invitation-metadata) to track invitation sources or assign attributes +- [Create and manage organizations](/docs/guides/organizations/create-and-manage) to see metadata in action +- [Check roles and permissions](/docs/guides/organizations/check-access) to control access based on metadata values diff --git a/docs/guides/organizations/org-slugs-in-urls.mdx b/docs/guides/organizations/org-slugs-in-urls.mdx index 995432a27d..361c3d8263 100644 --- a/docs/guides/organizations/org-slugs-in-urls.mdx +++ b/docs/guides/organizations/org-slugs-in-urls.mdx @@ -19,7 +19,7 @@ metadata: }, { title: "Enable organization slugs for your application", - link: "/docs/guides/organizations/overview#organization-slugs", + link: "/docs/guides/organizations/configure#organization-slugs", icon: "globe", } ]} @@ -31,7 +31,7 @@ metadata: ]} /> -Organization slugs are human-readable URL identifiers that help users reference which organization they're working in. A common pattern for organization-scoped areas in an application is to include the organization slug in the URL path. +Organization slugs are human-readable URL identifiers (like `acme-corp` or `marketing-team`) that help users reference which organization they're working in. A common pattern for organization-scoped areas in an application is to include the organization slug in the URL path, making links sharable and providing clear context about which tenant the page belongs to. For example, a B2B application named "Petstore" has two customer organizations: **Acmecorp** and **Widgetco**. Each organization uses its name as a slug in the URL: @@ -45,19 +45,19 @@ Alternatively, [organization IDs](/docs/reference/javascript/organization#proper ### When to use organization slugs -This feature is intended for apps that **require** organization slugs in URLs. **Adding slugs to URLs isn't recommended unless necessary.** +This feature is intended for apps that **require** organization slugs in URLs. **We don't recommend adding slugs to URLs unless necessary.** Use organization slugs if: -- Users frequently share links for public-facing content (e.g., documentation, marketing materials, and third-party blogs) -- Users regularly switch between multiple organizations -- Organization-specific URLs provide meaningful context +- Users frequently share links for public-facing content (e.g., documentation, marketing materials, and third-party blogs). +- Users regularly switch between multiple organizations. +- Organization-specific URLs provide meaningful context. **Don't** use organization slugs if: -- Most users belong to only one organization -- You want to keep URLs simple and consistent -- You're primarily using the Clerk session for organization context +- Most users belong to only one organization. +- You want to keep URLs simple and consistent. +- You're primarily using the Clerk session for organization context. This guide shows you how to add organization slugs to your app's URLs, configure Clerk components to handle slug-based navigation, and access organization data based on the URL slug at runtime. @@ -111,7 +111,7 @@ This guide shows you how to add organization slugs to your app's URLs, configure ## Configure `clerkMiddleware()` to set the active organization > [!TIP] - > If your app doesn't use `clerkMiddleware()`, or you prefer to manually set the [active organization](!active-organization), use the [`setActive()`](/docs/reference/javascript/clerk) method to control the active organization on the client-side. + > If your app doesn't use `clerkMiddleware()`, or you prefer to manually set the [active organization](/docs/guides/organizations/overview#how-do-organizations-work), use the [`setActive()`](/docs/reference/javascript/clerk) method to control the active organization on the client-side. With [`clerkMiddleware()`](/docs/reference/nextjs/clerk-middleware), you can use the [`organizationSyncOptions`](/docs/reference/nextjs/clerk-middleware#organization-sync-options) property to declare URL patterns that determine whether a specific organization should be activated. @@ -155,7 +155,7 @@ This guide shows you how to add organization slugs to your app's URLs, configure Failed activation occurs if no organization with the specified slug exists, or if the given user isn't a member of the organization. When this happens, the middleware won't change the active organization, leaving the previously active one unchanged. - For troubleshooting, a message will also be logged on the server: + For troubleshooting, Clerk will also log a message on the server: > Clerk: Organization activation handshake loop detected. This is likely due to an invalid organization ID or slug. Skipping organization activation. diff --git a/docs/guides/organizations/overview.mdx b/docs/guides/organizations/overview.mdx index c91c3fca85..7ad9ab8ea0 100644 --- a/docs/guides/organizations/overview.mdx +++ b/docs/guides/organizations/overview.mdx @@ -1,190 +1,56 @@ --- title: Organizations -description: Learn how to use Clerk Organizations to build scalable B2B auth features, user management, role based access control (RBAC), and per-organization invitation flows into your B2B SaaS. +description: Learn what Clerk organizations are, how they work, and how to build secure multi-tenant B2B applications with team workspaces, role-based access control, and streamlined enrollment. metadata: - title: Overview - Build a B2B/B2C multi-tenant SaaS with Clerk Organizations + title: Organizations - Build multi-tenant B2B applications --- -Organizations are a flexible and scalable way to manage users and their access to resources within your Clerk application. With organizations, you can assign specific roles and permissions to users, making them useful for managing projects, coordinating teams, or facilitating partnerships. +Organizations let you group users with roles and permissions. This lets you build multi-tenant B2B apps like Slack (workspaces), Linear (teams), or Vercel (projects) where users switch between different team contexts. -> [!NOTE] -> To explore organizations in Clerk, check out the demo apps: -> [https://github.com/clerk/orgs](https://github.com/clerk/orgs) - -## Enable organizations in your application - -Organizations are disabled by default. - -To enable organizations: - -1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page. -1. Select **Enable Organizations**. - -Once organizations are enabled, you will be presented with the default settings, roles, and permissions that are applied to all organizations in that application instance. The following sections will explain these settings in more detail. - -## Roles and permissions - -Roles determine a user's level of access and permissions within an organization. Learn more about [how roles and permissions work and how to create your own with Clerk](/docs/guides/organizations/roles-and-permissions). - -## Membership limit - -There is no limit to the number of organizations a user can be a member of. - -However, there is a limit to how many total members can be in a single organization. By default, the membership limit is set to 5 members. To change this limit, scroll to the **Default membership limit** section and update the membership limit. - -If you are on the Free plan, you can update the membership limit to a maximum of 5 members. - -If you have the Pro plan, you can set the membership limit to unlimited. - -You can also change this limit on a per-organization basis: - -1. In the top in the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/~/organizations). -1. Select the organization you want to update. -1. In the **Membership limit** section, update the membership limit. Note that this will not apply to organizations that already exist. - -## Allow new members to delete organizations - -By default, organizations are deletable. Any member with the "Delete organization" permission can delete an organization. To prevent organizations from being deleted, you can disable the ability to delete organizations by following these steps: - -1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page. -1. Disable **Allow new members to delete organizations**. Note that this will not apply to organizations that already exist. - -## Verified domains - -Verified domains can be used to streamline enrollment into an organization. For example, if the domain `@clerk.com` is added to an organization, any user with a `@clerk.com` email address can be automatically invited or be suggested to join this organization. This feature is useful for organizations that want to restrict membership to users with specific email domains. See the [guide on verified domains](/docs/guides/organizations/verified-domains) for more information. - -## Allow personal accounts - -In the Clerk Dashboard, there are two types of workspaces: - -- **Personal account**: A personal account/workspace is a user's unique, individual space, independent of any organization. -- **Organization workspace**: An organization workspace is owned and managed by an organization, which can have multiple members, also known as collaborators. The organization workspace that a user is currently viewing is called the [active organization](!active-organization). - -Most multi-tenant applications want every user to be part of an organization rather than operating in an isolated personal account. Accordingly, **personal accounts are disabled by default** once you enable organizations. After signing up, [a user must create or join an organization before they can proceed](/docs/guides/configure/session-tasks). - -To enable personal accounts for your application, toggle **Allow personal accounts** in the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page. - -> [!IMPORTANT] -> Personal accounts being disabled by default was released on August 22, 2025. Applications created before this date will not be able to see the **Allow personal accounts** setting, because personal account were enabled by default. - -## Organization slugs - -Organization slugs are human-readable URL identifiers that help users reference which organization they're working in. - -To enable it, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page in the Clerk Dashboard. - -When enabled, organization slugs will be displayed in the [``](/docs/reference/components/organization/create-organization), [``](/docs/reference/components/organization/organization-list), and [``](/docs/reference/components/organization/organization-switcher) components. +Users can belong to multiple organizations, and Clerk provides the organization context (memberships, roles, and the active organization) in each session. You can then use this context to control what data to show and what actions to allow. -> [!IMPORTANT] -> Organization slugs are disabled by default for applications created after October 7, 2025. For applications created before this date, you can opt to disable it. - -## Active organization - -When a user is a member of an organization, they can switch between different organizations. The organization workspace that a user is currently viewing is called the **active organization**. The active organization determines which organization-specific data the user can access and which role and related permissions they have within the organization. - -When personal accounts are disabled (the default), users must select or create an organization to continue. This is handled automatically in the [session tasks flow](/docs/guides/configure/session-tasks). - -When personal accounts are enabled, users initially sign in to their personal account with **no** active organization set. The easiest way to allow users to set an organization as active is to use the [``](/docs/reference/components/organization/organization-switcher) component. If the prebuilt components don't meet your specific needs or if you require more control over the logic, you can also use the `setActive()` method, which is returned by the [`useOrganizationList()`](/docs/reference/hooks/use-organization-list) hook. If you aren't using hooks, you can access the `setActive()` method from the [`Clerk`](/docs/reference/javascript/clerk#set-active) object. - -## Monthly Active Organization (MAO) - -The number of organizations you can have in a single Clerk application depends on your [Clerk plan](/pricing){{ target: '_blank' }} and the type of instance (development or production), and is measured by Monthly Active Organizations (MAOs). An MAO is an organization with at least two users that have signed in that month, at least one of which must have interacted with the organization during the current billing cycle. - -With the Free plan: - -- In development instances, you can have _up to_ 50 MAOs in a single Clerk application. Each MAO can have _up to_ 5 members. -- In production instances, you can have up to 100 MAOs in a single Clerk application. Each MAO can have up to 5 members. - -With the Pro plan: - -- In development instances, you can have an unlimited number of MAOs in a single Clerk application _for free_. Each MAO can have an unlimited number of members. -- In production instances, you can have up to 100 MAOs in a single Clerk application _for free_. Each MAO after the first 100 costs $1.00 per month. Each MAO can have an unlimited number of members. - -For more information on pricing, see the [pricing page](/pricing){{ target: '_blank' }}. - -If you need more organizations or custom pricing, contact the [sales team](/contact/sales){{ target: '_blank' }} to upgrade to the Enterprise plan. - -## Manage organizations - -As the application owner, you have control over all of the organizations within your application - both those created by you and those created by your users. You can create, update, and delete organizations, as well as manage their members and settings. - -There are two ways to manage organizations: - -- [In the Clerk Dashboard](#manage-organizations-in-the-clerk-dashboard) -- [In your application](#manage-organizations-in-your-application) - -### Manage organizations in the Clerk Dashboard - -To manage organizations in the Clerk Dashboard: - -1. In the top in the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/~/organizations). Here, you can view and manage all organizations in your application. -1. Select a specific organization to view its details, members, invitations, and settings. Here, you can update the organization's name, slug, logo, and public and private metadata. You can also set the organization's [membership limit](#membership-limit). - -### Manage organizations in your application - -For managing organizations in your application, Clerk provides a set of prebuilt components: - -- [``](/docs/reference/components/organization/create-organization) - A form for a user to create a new organization. -- [``](/docs/reference/components/organization/organization-profile) - A profile page for the user's currently active organization. -- [``](/docs/reference/components/organization/organization-list) - A list of organizations that a user is a member of. -- [``](/docs/reference/components/organization/organization-switcher) - A dropdown menu that handles all organization flows. It allows a user to create an organization, switch between organizations, and view their organization's profile, which allows them to manage the organization's settings, invitations, and current members. If [personal accounts are enabled](/docs/guides/organizations/overview#allow-personal-accounts), users can also switch to their personal account. - -If the prebuilt components don't meet your specific needs or if you require more control over the logic, you can rebuild and customize the existing Clerk flows using the Clerk API. See the [custom flows](/docs/guides/development/custom-flows/overview) for more information. - -## Create an organization - -There are two ways to create an organization: - -- [In the Clerk Dashboard](#create-an-organization-in-the-clerk-dashboard) -- [In your application](#create-an-organization-in-your-application) - -How many organizations you can create depends on how many [MAOs](#monthly-active-organization-mao) you have. - -### Create an organization in the Clerk Dashboard +> [!NOTE] +> To explore organizations in Clerk, check out the [demo apps](https://github.com/clerk/orgs). -To create an organization in the Clerk Dashboard: +## How do organizations work? -1. In the top in the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/~/organizations). -1. Select the **Create Organization** button. -1. Enter the organization's name. Optionally, upload the organization's logo, enter the organization's slug, and select the organization's owner. The slug is a unique identifier for the organization that is used in URLs, such as `example-name`. +Organizations live within your Clerk application. Each application can contain multiple organizations, and each organization can have multiple users. You define [roles and permissions](/docs/guides/organizations/roles-and-permissions) once at the application level, and they apply across all organizations within that application. -### Create an organization in your application +![Relationship between Clerk organization, users, roles and permissions](/docs/images/orgs/relationship-diagram.png) -By default, users have the permission to create organizations within your application. To configure this permission for all users: +The organization that a user is currently viewing is called the **active organization**. The active organization determines which organization-specific data the user can access and which role and related permissions they have within the organization. -1. In the Clerk Dashboard, navigate to the [**Organizations Settings**](https://dashboard.clerk.com/~/organizations-settings) page. -1. At the bottom of the page, in the **Limit creation** section, enable/disable **Allow new users to create organizations**. You can also configure the number of organizations that can be created by each user. By default, each user can create an unlimited number of organizations. +Clerk measures organization usage through **Monthly Active Organizations (MAOs)**. An MAO is an organization with at least two users that have signed in that month, where at least one has interacted with the organization during the current billing cycle. Free plans include up to 50 MAOs in development and 100 in production. Pro plans offer unlimited development MAOs and start at 100 free production MAOs, then $1 per additional MAO. Refer to the [pricing page](/pricing){{ target: '_blank' }} for complete details. -If you want to only configure this permission for a specific user, you can override it on a per-user basis on the user's profile page in the Clerk Dashboard: +### How do I set an organization as active? -1. In the top in the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/~/users). -1. Select the user you want to update. -1. In the **User permissions** section, enable/disable **Allow user to create organizations**. +By default, personal accounts are disabled and users are required to be a member of at least one organization, which will be set as the active organization. -When a user creates an organization, they become the organization's admin. As the organization's admin, they have full control over the organization, including the ability to update the organization's settings, invite users to join the organization, and manage the organization's members. +If personal accounts are enabled, when a user signs in, they will sign in to their personal account and **no** active organization will be set. The easiest way to allow users to set an organization as active is to use the [``](/docs/reference/components/organization/organization-switcher) component. If the prebuilt components don't meet your specific needs or if you require more control over the logic, you can use the [`setActive()`](/docs/reference/javascript/clerk#set-active) method returned by the [`useOrganizationList()`](/docs/reference/hooks/use-organization-list) hook, or access it directly from the [`Clerk`](/docs/reference/javascript/clerk) object. -A single user within one of your applications can create _up to_ 100 organizations in that application. If you need users to be able to create more organizations than this, [contact support](/contact/support){{ target: '_blank' }} to have the limit raised. +### Core workflow -The easiest way to allow users to create organizations is to use the [``](/docs/reference/components/organization/create-organization) and/or [``](/docs/reference/components/organization/organization-switcher) components. The `` component is more comprehensive, as it handles all organization flows. +The core workflow when working with organizations can follow something along the lines of: -## Organization invitations +1. **Create**: You can create organizations [in the Clerk Dashboard](https://dashboard.clerk.com/~/organizations), or end users can create them in your application through prebuilt components or APIs. Each organization has a profile, settings, and [metadata](/docs/guides/organizations/metadata). Users can belong to multiple organizations and switch between them with the [``](/docs/reference/components/organization/organization-switcher) component. Learn more about [creating and managing organizations](/docs/guides/organizations/create-and-manage). -[Learn how to create and revoke organization invitations](/docs/guides/organizations/invitations). +1. **Add members**: You can add members to organizations in different ways depending on your needs: -## Manage enterprise connections + - [**Invitations**](/docs/guides/organizations/invitations) for bottom-up adoption, where individual users invite teammates with precise control over roles. + - [**Verified domains**](/docs/guides/organizations/verified-domains) for company-wide rollouts, where Clerk automatically invites users with matching email domains (who can join immediately) or suggests they join (requiring admin approval). + - [**Enterprise connections**](/docs/guides/organizations/sso) (SAML or OIDC) for top-down deployments managed by IT with centralized authentication through an Identity Provider (IdP). -Single Sign-On (SSO) can be configured at the organization level, allowing organizations to use their own Identity Provider (IdP) for authentication. These are called **enterprise connections**. When configured: + You can combine these approaches: use manual invitations for external contractors alongside domain-based enrollment for employees. The active organization determines which members and roles apply to the current context. -- Users can sign in through their organization's configured IdP -- Users are **automatically added as members** of the organization upon successful authentication -- Organizations can maintain their existing identity management workflows -- SAML 2.0 and OIDC protocols are supported +1. **Control access**: You can manage access to content or entire pages using roles and permissions. Default admin and member roles cover common cases, while custom roles and permissions provide fine-grained access for more complex needs. You can perform [authorization checks](!authorization-check) in both frontend and backend code. -For instructions on how to set up and manage SSO for your organizations, see the [dedicated guide](/docs/guides/organizations/sso). +Beyond these core steps, you can also monitor organization health and growth with analytics in the Clerk Dashboard. This helps you spot which organizations are growing, staying active, or dropping off, so you know what's working and where you might need attention. ## Next steps -- [Learn how to limit access to content or entire routes based on a user's role or permissions](/docs/guides/secure/authorization-checks) -- [Learn how to restrict memberships to an organization based on their email domain](/docs/guides/organizations/verified-domains) -- [Learn how to manually invite users to an organization](/docs/guides/organizations/invitations) -- [Learn how to automatically add users to an organization based on their email domain](/docs/guides/organizations/sso) +Now that you understand what organizations are and how they work, here's how to implement them: + +- [Configure organization settings](/docs/guides/organizations/configure) +- [Create and manage organizations](/docs/guides/organizations/create-and-manage) +- [Invite members](/docs/guides/organizations/invitations) +- [Set up roles and permissions](/docs/guides/organizations/roles-and-permissions) diff --git a/docs/guides/organizations/roles-and-permissions.mdx b/docs/guides/organizations/roles-and-permissions.mdx index 8b5c9046c8..4db37883af 100644 --- a/docs/guides/organizations/roles-and-permissions.mdx +++ b/docs/guides/organizations/roles-and-permissions.mdx @@ -1,17 +1,17 @@ --- title: Roles and permissions -description: Step-by-step guide on how to implement role based access control (RBAC) in B2C/B2B SaaS apps. You can set as many custom roles, assign privileges and access permissions, all using Clerk Organizations. +description: Implement role-based access control (RBAC) in your application. Set custom roles, assign privileges, and control access to resources using Clerk Organizations. metadata: title: B2B/B2C roles and permissions with Clerk Organizations --- -Clerk supports modeling your own custom role and permissions to control access to resources within your application when you use [organizations](/docs/guides/organizations/overview). +Roles and permissions let you control who can access specific resources and perform certain actions within each organization. Clerk provides two default roles - **admin** and **member** - that cover most common use cases. You can also create custom roles and fine-grained permissions that fit your application's specific features and team setup. ## Roles -Roles determine a user's level of access to the organization. You can extend a role's privileges and access to resources by adding [permissions](#permissions). +Each role defines what users can do and access within an organization. You can extend a role's capabilities by adding [permissions](#permissions). ### Default roles @@ -22,7 +22,7 @@ For each instance, there are currently two default roles: ### The **Creator** role -When a user creates a new organization, they're automatically added as its first member and assigned the organization's designated **Creator** role. By default, that role is `org:admin`. +When a user creates a new organization, Clerk automatically adds them as its first member and assigns them the organization's designated **Creator** role. By default, that role is `org:admin`. You cannot delete an organization role if it's used as the organization's **Creator** role. But, you _can_ reassign the **Creator** role to any other role with the right permissions. For example, if you want to delete the `admin` role, you will have to assign another role as the **Creator** role. @@ -68,11 +68,11 @@ To create a new role: ### Change a user's role -You can change a user's role in the Clerk Dashboard, or in your application, such as in the [``](/docs/reference/components/organization/organization-switcher) component. +You can change a user's role in the Clerk Dashboard, or in your application using the [``](/docs/reference/components/organization/organization-switcher) component. To change a user's role in the Clerk Dashboard: -1. In the top in the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/~/organizations) and select an organization. +1. In the Clerk Dashboard, select [**Organizations**](https://dashboard.clerk.com/~/organizations) and select an organization. 1. Select the **Members** tab. 1. In the list of members, find the one whose role you want to change. 1. Select another role from their role dropdown. @@ -107,7 +107,7 @@ Clerk's system permissions consist of the following: You can assign these system permissions to any role. > [!WARNING] -> System permissions aren't included in [session claims](/docs/guides/sessions/session-tokens#default-claims). To check permissions on the server-side, you must [create custom permissions](#custom-permissions). +> System permissions aren't included in [session claims](/docs/guides/sessions/session-tokens#default-claims). If you need to check permissions on the server-side, you must [create custom permissions](#custom-permissions) for authorization checks in your application code. ### Custom permissions @@ -138,7 +138,9 @@ It's best practice to always verify whether or not a user is **authorized** to a ## Next steps -- [Learn how to limit access to content or entire routes based on a user's role or permissions](/docs/guides/secure/authorization-checks) +Now that you've set up roles and permissions, you can: + +- [Perform authorization checks](/docs/guides/secure/authorization-checks) to limit access to content or entire routes based on a user's role or permissions - [Learn how to automatically invite users to an organization based on their email domain](/docs/guides/organizations/verified-domains) - [Learn how to manually invite users to an organization](/docs/guides/organizations/invitations) -- [Learn how to automatically add users to an organization based on their email domain](/docs/guides/organizations/sso) +- [Learn how to automatically add users to an organization through enterprise SSO](/docs/guides/organizations/sso) diff --git a/docs/guides/organizations/sso.mdx b/docs/guides/organizations/sso.mdx index ef132a1c46..ad40d67356 100644 --- a/docs/guides/organizations/sso.mdx +++ b/docs/guides/organizations/sso.mdx @@ -1,59 +1,82 @@ --- title: Organization-level enterprise SSO -description: Integrate as many enterprise SSO methods within Clerk Organizations. Enable SAML SSO, OAuth/OIDC, and other secure MFA/single sign-on options for B2B SaaS apps. +description: Integrate as many enterprise SSO methods within Clerk organizations. Enable SAML SSO, OAuth/OIDC, and other secure MFA/single sign-on options for B2B SaaS apps. metadata: title: Set up organization-level SAML and OIDC for B2B/B2C apps --- -Clerk supports enabling enterprise SSO connections for specific organizations. When users sign up or sign in using an organization's enterprise connection, they're automatically added as members of that organization and assigned the [default role](/docs/guides/organizations/roles-and-permissions#the-default-role-for-members), which can be either `member` or `admin`. +Clerk provides enterprise single sign-on (SSO) through a feature called [**enterprise connections**](/docs/guides/configure/auth-strategies/enterprise-connections/overview). You can enable enterprise connections for specific organizations, allowing members to authenticate through their company's identity provider using SAML or OIDC protocols. -## Add an enterprise SSO connection for an organization +When users sign up or sign in using an organization's enterprise connection, Clerk automatically adds them as members of that organization and assigns them the [default role](/docs/guides/organizations/roles-and-permissions#the-default-role-for-members). This process is known as [Just-in-Time (JIT) provisioning](/docs/guides/configure/auth-strategies/enterprise-connections/jit-provisioning). -Clerk supports enterprise SSO via [SAML](/docs/guides/configure/auth-strategies/enterprise-connections/overview#saml) or via the [OpenID Connect (OIDC) protocol](/docs/guides/configure/auth-strategies/enterprise-connections/overview#oidc), either through EASIE or by integrating with any OIDC-compatible provider. +## When to use enterprise SSO -To add an enterprise SSO connection for an organization, follow the appropriate guide based on the platform you want to use, such as the [Google SAML guide](/docs/guides/configure/auth-strategies/enterprise-connections/saml/google). When configuring the connection in the Clerk Dashboard, there will be an option to select the **Organization** for which you want to enable this connection. If you don't select an organization, the connection will be added for your entire application. +Enterprise SSO works well when customers require centralized authentication through their Identity Provider. This approach fits scenarios where: -> [!WARNING] -> A domain used for enterprise SSO can't be used as a [verified domain](/docs/guides/organizations/verified-domains) for the same organization. +- Enterprise customers have security requirements that mandate IdP-based authentication. +- IT teams need to manage user provisioning from a central location. +- Organizations want to maintain existing identity management workflows. -## Onboarding flows +If you need manual control over who joins and their [roles](/docs/guides/organizations/roles-and-permissions), use [invitations](/docs/guides/organizations/invitations). If you want automatic enrollment without IdP requirements, use [verified domains](/docs/guides/organizations/verified-domains). -The two common onboarding flows for organizations with enterprise SSO are to either create an organization first or to have users initiate the setup themselves. +## Common onboarding flows -#### Organization created first (top-down approach) +The timing of when you set up enterprise SSO depends on how customers adopt your product. The two common approaches are to create the organization and configure SSO before users sign in (top-down) or to let users start individually and add SSO later (bottom-up). + +### Organization created first (top-down approach) This flow is common for enterprise sales where the relationship is established before users access the application. -1. [Create an organization](/docs/guides/organizations/overview#create-an-organization) for your customer through the Clerk Dashboard. +1. [Create an organization](/docs/guides/organizations/create-and-manage#create-an-organization) for your customer through the Clerk Dashboard. 1. Collaborate with the customer's IT administrator to obtain the necessary configuration details. 1. Configure the enterprise SSO connection for the organization. 1. Invite users to the organization, who can then sign in using enterprise SSO. -#### User-initiated setup (bottom-up approach) +### User-initiated setup (bottom-up approach) This flow is common when individual users try the product before company-wide adoption. 1. An end user signs up to evaluate your application, starting with an individual account. -1. After adopting the application, the user [creates an organization](/docs/guides/organizations/overview#create-an-organization) for their company. +1. After adopting the application, the user [creates an organization](/docs/guides/organizations/create-and-manage#create-an-organization) for their company. 1. Configure enterprise SSO for the organization through the Clerk Dashboard. 1. All subsequent users from that organization can now sign in using enterprise SSO. +## Add an enterprise SSO connection for an organization + +Clerk supports enterprise SSO via [SAML](/docs/guides/configure/auth-strategies/enterprise-connections/overview#saml) or via the [OpenID Connect (OIDC) protocol](/docs/guides/configure/auth-strategies/enterprise-connections/overview#oidc), either through EASIE or by integrating with any OIDC-compatible provider. + +To add an enterprise SSO connection for an organization, go to the [Enterprise connections](/docs/guides/configure/auth-strategies/enterprise-connections/overview) docs and follow the appropriate guide based on the platform you want to use, such as the [Google SAML guide](/docs/guides/configure/auth-strategies/enterprise-connections/saml/google). When configuring the connection in the Clerk Dashboard, there will be an option to select the **Organization** for which you want to enable this connection. If you don't select an organization, Clerk will add the connection for your entire application. + +> [!WARNING] +> A domain used for enterprise SSO can't be used as a [verified domain](/docs/guides/organizations/verified-domains) for the same organization. + ## Enforce enterprise SSO by domain -Enterprise SSO connections are enforced on a per-domain basis in organizations, enabling flexible access management: +Clerk enforces enterprise SSO connections on a per-domain basis in organizations, enabling flexible access management: - Configure enterprise SSO for your primary domain (e.g., `company.com`) to enforce enterprise SSO authentication for employees. - Add additional domains without enterprise SSO for external collaborators (e.g., contractors, consultants). - Each domain in an organization can have different authentication requirements. -## Manage memberships +## Remove a member from your organization + +Users who joined through an enterprise connection cannot leave the organization on their own. You can remove them through the Clerk Dashboard, the [Backend API](/docs/reference/backend-api/tag/organization-memberships/delete/organizations/\{organization_id}/memberships/\{user_id}){{ target: '_blank' }}, or by another member with the [manage members permission](/docs/guides/organizations/roles-and-permissions#system-permissions). + +Removed users will automatically rejoin the organization on their next sign-in unless you also remove them from the IdP or disconnect the enterprise connection. + +## Move an enterprise connection to a different organization -### Remove a member from your organization +When you reassign an enterprise connection to a new organization, existing members stay in the original organization. They will automatically join the new organization the next time they sign in. -When a user is tied to an organization through their enterprise connection, they cannot leave the organization themselves, but they can be removed either in the Clerk Dashboard, using [Clerk's Backend API](/docs/reference/backend-api/tag/organization-memberships/delete/organizations/\{organization_id}/memberships/\{user_id}) endpoint, or by another organization member with the [manage members permission](/docs/guides/organizations/roles-and-permissions#system-permissions) (`org:sys_memberships:manage`). However, the user will be added back to the organization on next sign-in, unless they are removed from the IdP or the enterprise connection is no longer associated with the organization. +To remove these users from the original organization, use either the [Backend API](/docs/reference/backend-api/tag/organization-memberships/delete/organizations/\{organization_id}/memberships/\{user_id}){{ target: '_blank' }} or the Clerk Dashboard. -## Update an organization from an existing enterprise connection +## Next steps -When transitioning an enterprise connection to a new organization, existing members will remain part of the original organization. However, they will automatically join the new organization upon their next sign-in. +Now that you've set up enterprise SSO, you can: -To remove members from the original organization, you have two options: utilize [Clerk's Backend API](/docs/reference/backend-api/tag/organization-memberships/delete/organizations/\{organization_id}/memberships/\{user_id}) or manage memberships directly through the Clerk Dashboard. +- [Learn more about enterprise connections](/docs/guides/configure/auth-strategies/enterprise-connections/overview) for advanced configuration options +- [Understand JIT provisioning](/docs/guides/configure/auth-strategies/enterprise-connections/jit-provisioning) to customize how users are automatically added to organizations +- [Configure verified domains](/docs/guides/organizations/verified-domains) for users who don't use SSO +- [Invite specific users](/docs/guides/organizations/invitations) to your organization +- [Set up roles and permissions](/docs/guides/organizations/roles-and-permissions) to control what SSO users can access +- [Configure default roles](/docs/guides/organizations/configure#default-roles) for users joining via SSO diff --git a/docs/guides/organizations/verified-domains.mdx b/docs/guides/organizations/verified-domains.mdx index 49d8b1c6cb..903ffa0745 100644 --- a/docs/guides/organizations/verified-domains.mdx +++ b/docs/guides/organizations/verified-domains.mdx @@ -5,7 +5,7 @@ metadata: title: Verified domains within Clerk Organizations (Step-by-Step) --- -Clerk's **verified domains** feature is useful for organizations that want to restrict membership to users with specific email domains, and automatically invite or suggest users with that domain to join an organization. For example, if the domain `@clerk.com` is verified, any user with an email address ending in `@clerk.com` can be automatically invited or be suggested to join an organization with that domain. The role assigned to this user will be the role set as the [**Default** role](/docs/guides/organizations/roles-and-permissions#the-default-role-for-members) in the organization settings page. +Clerk's **verified domains** feature is useful for organizations that want to restrict membership to users with specific email domains, and automatically invite or suggest users with that domain to join an organization. For example, if the domain `@clerk.com` is verified, any user with an email address ending in `@clerk.com` can be automatically invited or be suggested to join an organization with that domain. Clerk assigns users the [**Default** role](/docs/guides/organizations/roles-and-permissions#the-default-role-for-members) set in the organization settings page. A verified domain cannot be a disposable domain or common email provider. For example, you cannot create a verified domain for `@gmail.com`. @@ -14,6 +14,16 @@ A verified domain cannot be a disposable domain or common email provider. For ex The easiest way to add and verify domains, and manage all settings related to verified domains is to use Clerk's [``](/docs/reference/components/organization/organization-switcher) component. +## When to use verified domains + +Verified domains work well when you want to streamline enrollment for users with company email addresses. This approach fits scenarios where: + +- Company-wide rollouts need automatic or suggested membership. +- Reducing onboarding friction for employees with approved email domains. +- Enrollment can happen based on email domain without manual approval. + +If you need precise control over specific people and their roles, use [invitations](/docs/guides/organizations/invitations). If customers require authentication through their Identity Provider, use [enterprise SSO](/docs/guides/organizations/sso). + ## Enable verified domains Enabling verified domains applies to all organizations and cannot currently be managed on a per-organization basis. @@ -29,7 +39,7 @@ In order to enable this feature: You can enable the following enrollment modes to be available for your application: -- [**Automatic invitation**](#automatic-invitations) - Users are automatically invited to join the organization when they sign-up and can join anytime. +- [**Automatic invitation**](#automatic-invitations) - Clerk automatically invites users to join the organization when they sign up and they can join anytime. - [**Automatic suggestion**](#automatic-suggestions) - Users receive a suggestion to request to join, but must be approved by an admin before they are able to join the organization. Then, in your application, when a user with the `org:sys_domains:manage` permission has added and verified a domain, they can enable an enrollment mode. Only one enrollment mode can be enabled for a verified domain at a time. @@ -44,15 +54,15 @@ After sign-up, a user will receive a **suggestion** for the organization if thei ### Membership requests -Membership requests are requests from users who saw an organization suggestion and requested to join an organization. Membership requests are only available for organizations that have the **Verified domains** feature enabled and the **Automatic suggestions** feature enabled in both the Dashboard and for the specific domain. +Membership requests are requests from users who saw an organization suggestion and requested to join an organization. Membership requests are only available for organizations that have the **Verified domains** and **Automatic suggestion** features enabled in both the Dashboard and for the specific domain. When a user sends an organization membership request, users with the `org:sys_memberships:manage` permission (by default, admins) will see a notification on their `` component. They will need to accept the request before the user can join the organization. ## Add and verify domains -Domains can be added and verified under an organization by any user with the `org:sys_domains:manage` permission. By default, admins have this permission. To add and verify domains in the [``](/docs/reference/components/organization/organization-switcher) component, select the **General** tab. There will be a **Verified domains** section. +Any user with the `org:sys_domains:manage` permission can add and verify domains under an organization. By default, admins have this permission. To add and verify domains in the [``](/docs/reference/components/organization/organization-switcher) component, select the **General** tab. There will be a **Verified domains** section. -Domains can be verified through an email verification code sent to an email that matches the domain. If the user adding the domain already has a verified email using that domain in their account, the domain will be automatically verified. +Domains can be verified through an email verification code sent to an email that matches the domain. If the user adding the domain already has a verified email using that domain in their account, Clerk will automatically verify the domain. An application instance may only have one verified domain of the same name, and an organization may only have one domain of the same name (verified or unverified). @@ -77,3 +87,12 @@ domain.attemptAffiliationVerification({ code: '123456' }) // update domain enrollment mode domain.updateEnrollmentMode({ enrollmentMode: 'automatic_invitation' }) ``` + +## Next steps + +Now that you've configured verified domains, you can: + +- [Set up enterprise SSO](/docs/guides/organizations/sso) for centralized authentication through an Identity Provider +- [Invite specific users](/docs/guides/organizations/invitations) who don't match your verified domain +- [Set up roles and permissions](/docs/guides/organizations/roles-and-permissions) to control what auto-enrolled users can access +- [Configure default roles](/docs/guides/organizations/configure#default-roles) for users joining via verified domains diff --git a/docs/guides/secure/authorization-checks.mdx b/docs/guides/secure/authorization-checks.mdx index 93dbbb36f7..9250ac5959 100644 --- a/docs/guides/secure/authorization-checks.mdx +++ b/docs/guides/secure/authorization-checks.mdx @@ -1,6 +1,6 @@ --- -title: Authorize users -description: Learn how to verify and validate user roles and permissions within Clerk to maintain secure access control. We provide a collection of utility functions and components that allow developers to perform authorization checks. +title: Authorization checks +description: Learn how to verify and validate user roles and permissions within Clerk to maintain secure access control. metadata: title: Verifying user permissions with Clerk --- diff --git a/docs/guides/sessions/manual-jwt-verification.mdx b/docs/guides/sessions/manual-jwt-verification.mdx index 27cec70633..8a07eba212 100644 --- a/docs/guides/sessions/manual-jwt-verification.mdx +++ b/docs/guides/sessions/manual-jwt-verification.mdx @@ -41,7 +41,7 @@ The following example uses the `authenticateRequest()` method to verify the sess ### Optional: Check for a `sts` claim - If you are using Clerk's [organizations](/docs/guides/organizations/overview) feature and [have not enabled personal accounts](/docs/guides/organizations/overview#allow-personal-accounts), users are _required to be part of an organization before accessing your application_. If the user has completed registration, but is not yet part of an organization, a valid session token will be created, but the token will contain a `sts` (status) claim set to `pending`. You may want to reject requests to your backend with pending statuses to ensure that users are not able to work around the organization requirement. + If you are using Clerk's [organizations](/docs/guides/organizations/overview) feature and [have not enabled personal accounts](/docs/guides/organizations/configure#enable-organizations), users are _required to be part of an organization before accessing your application_. If the user has completed registration, but is not yet part of an organization, a valid session token will be created, but the token will contain a `sts` (status) claim set to `pending`. You may want to reject requests to your backend with pending statuses to ensure that users are not able to work around the organization requirement. ### Finished diff --git a/docs/manifest.json b/docs/manifest.json index 833927fbf0..1180cd3129 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -661,8 +661,12 @@ "href": "/docs/guides/organizations/overview" }, { - "title": "Verified domains", - "href": "/docs/guides/organizations/verified-domains" + "title": "Configure organizations", + "href": "/docs/guides/organizations/configure" + }, + { + "title": "Create and manage organizations", + "href": "/docs/guides/organizations/create-and-manage" }, { "title": "Roles and permissions", @@ -673,15 +677,19 @@ "href": "/docs/guides/organizations/invitations" }, { - "title": "Metadata", - "href": "/docs/guides/organizations/metadata" + "title": "Verified domains", + "href": "/docs/guides/organizations/verified-domains" }, { - "title": "Manage enterprise SSO connections", + "title": "Enterprise SSO", "href": "/docs/guides/organizations/sso" }, { - "title": "Use org slugs in URLs", + "title": "Set organization metadata", + "href": "/docs/guides/organizations/metadata" + }, + { + "title": "Use organization slugs in URLs", "href": "/docs/guides/organizations/org-slugs-in-urls" } ] diff --git a/docs/reference/components/billing/pricing-table.mdx b/docs/reference/components/billing/pricing-table.mdx index dca3c339ae..5bac704cd9 100644 --- a/docs/reference/components/billing/pricing-table.mdx +++ b/docs/reference/components/billing/pricing-table.mdx @@ -266,7 +266,7 @@ All props are optional. - `for` - `'user' | 'organization'` - A string that indicates whether the pricing table is for users or [organizations](/docs/guides/organizations/overview). If `'user'`, the pricing table will display a list of plans and features that **users** can subscribe to. If `'organization'`, the pricing table will display a list of plans and features that **organizations** can subscribe to. Defaults to `'user'`. + A string that indicates whether the pricing table is for users or [organizations](/docs/guides/organizations/create-and-manage). If `'user'`, the pricing table will display a list of plans and features that **users** can subscribe to. If `'organization'`, the pricing table will display a list of plans and features that **organizations** can subscribe to. Defaults to `'user'`. --- diff --git a/docs/reference/components/organization/organization-list.mdx b/docs/reference/components/organization/organization-list.mdx index 5320a7169d..8c259c23da 100644 --- a/docs/reference/components/organization/organization-list.mdx +++ b/docs/reference/components/organization/organization-list.mdx @@ -287,7 +287,7 @@ The `` component accepts the following properties, all of wh - `afterSelectPersonalUrl` - ((org: [Organization][org-ref]) => string) | string - The full URL or path to navigate to after selecting the [personal account](/docs/guides/organizations/overview#allow-personal-accounts). Defaults to `undefined`. + The full URL or path to navigate to after selecting the [personal account](/docs/guides/organizations/configure#enable-organizations). Defaults to `undefined`. --- @@ -308,7 +308,7 @@ The `` component accepts the following properties, all of wh - `hidePersonal` - `boolean` - A boolean that controls whether `` will include the user's [personal account](/docs/guides/organizations/overview#allow-personal-accounts) in the organization list. Setting this to `true` will hide the personal account option, and users will only be able to switch between organizations. Defaults to `false`. + A boolean that controls whether `` will include the user's [personal account](/docs/guides/organizations/configure#enable-organizations) in the organization list. Setting this to `true` will hide the personal account option, and users will only be able to switch between organizations. Defaults to `false`. --- diff --git a/docs/reference/components/organization/organization-profile.mdx b/docs/reference/components/organization/organization-profile.mdx index c714b625fe..570e653613 100644 --- a/docs/reference/components/organization/organization-profile.mdx +++ b/docs/reference/components/organization/organization-profile.mdx @@ -10,7 +10,7 @@ The `` component allows users to manage their organizatio This component's **General** tab displays the organization's information and the **Leave organization** button. Admins will be able to see the **Update profile** button, **Verified domains** section, and **Delete organization** button. -The **Members** tab shows the organization's members along with their join dates and roles. Admins will have the ability to invite a member, change a member's role, or remove them from the organization. Admins will have tabs within the **Members** tab to view the organization's [invitations](/docs/guides/organizations/overview#organization-invitations) and [requests](/docs/guides/organizations/verified-domains#membership-requests). +The **Members** tab shows the organization's members along with their join dates and roles. Admins will have the ability to invite a member, change a member's role, or remove them from the organization. Admins will have tabs within the **Members** tab to view the organization's [invitations](/docs/guides/organizations/invitations) and [requests](/docs/guides/organizations/verified-domains#membership-requests). The **Billing** tab displays the plans and features that are available to the organization, as well as the user's billing information, such as their invoices and payment methods. diff --git a/docs/reference/components/organization/organization-switcher.mdx b/docs/reference/components/organization/organization-switcher.mdx index b63cd362dd..437d135a83 100644 --- a/docs/reference/components/organization/organization-switcher.mdx +++ b/docs/reference/components/organization/organization-switcher.mdx @@ -6,7 +6,7 @@ sdk: astro, chrome-extension, expo, nextjs, nuxt, react, react-router, remix, ta ![The \ component allows a user to switch between their account types - their personal account and their joined organizations.](/docs/images/ui-components/organization-switcher.png){{ style: { maxWidth: '436px' } }} -The `` component allows a user to switch between their joined organizations. If [personal accounts are enabled](/docs/guides/organizations/overview#allow-personal-accounts), users can also switch to their personal account. This component is useful for applications that have a multi-tenant architecture, where users can be part of multiple organizations. It handles all organization-related flows, including full organization management for admins. Learn more about [organizations](/docs/guides/organizations/overview). +The `` component allows a user to switch between their joined organizations. If [personal accounts are enabled](/docs/guides/organizations/configure#enable-organizations), users can also switch to their personal account. This component is useful for applications that have a multi-tenant architecture, where users can be part of multiple organizations. It handles all organization-related flows, including full organization management for admins. Learn more about [organizations](/docs/guides/organizations/create-and-manage). ` component accepts the following properties, all o - `hidePersonal` - `boolean` - A boolean that controls whether `` will include the user's [personal account](/docs/guides/organizations/overview#allow-personal-accounts) in the organization list. Setting this to `true` will hide the personal account option, and users will only be able to switch between organizations. Defaults to `false`. + A boolean that controls whether `` will include the user's [personal account](/docs/guides/organizations/configure#enable-organizations) in the organization list. Setting this to `true` will hide the personal account option, and users will only be able to switch between organizations. Defaults to `false`. --- diff --git a/docs/reference/javascript/organization.mdx b/docs/reference/javascript/organization.mdx index 3dca293fb4..5f68dffd51 100644 --- a/docs/reference/javascript/organization.mdx +++ b/docs/reference/javascript/organization.mdx @@ -6,7 +6,7 @@ sdk: js-frontend The `Organization` object holds information about an organization, as well as methods for managing it. -To use these methods, you must have the **Organizations** feature [enabled in your app's settings in the Clerk Dashboard](/docs/guides/organizations/overview#enable-organizations-in-your-application). +To use these methods, you must have the **Organizations** feature [enabled in your app's settings in the Clerk Dashboard](/docs/guides/organizations/configure#enable-organizations). ## Properties @@ -317,7 +317,7 @@ For an example on how to use `getMemberships()`, see the [custom flow on managin Retrieve the list of membership requests for the currently [active organization](!active-organization). Returns a [`ClerkPaginatedResponse`][pag-ref] of [`OrganizationMembershipRequest`][org-mem-ref]-request) objects. > [!WARNING] -> You must have [**Organizations**](/docs/guides/organizations/overview#enable-organizations-in-your-application), and [**Verified domains** and **Automatic suggestion**][verified-domains-ref] enabled in your app's settings in the Clerk Dashboard. +> You must have [**Organizations**](/docs/guides/organizations/configure#enable-organizations), and [**Verified domains** and **Automatic suggestion**][verified-domains-ref] enabled in your app's settings in the Clerk Dashboard. ```ts function getMembershipRequests( diff --git a/docs/reference/javascript/overview.mdx b/docs/reference/javascript/overview.mdx index a3dfb872e6..a045254d31 100644 --- a/docs/reference/javascript/overview.mdx +++ b/docs/reference/javascript/overview.mdx @@ -38,4 +38,4 @@ The [`SignUp`](/docs/reference/javascript/sign-up) object holds the state of the ### `Organization` -Organizations are a flexible and scalable way to manage users and their access to resources within your Clerk application. With organizations, you can assign specific roles and permissions to users, making them useful for managing projects, coordinating teams, or facilitating partnerships. Users can belong to many organizations. One of them will be the [active organization](!active-organization) of the session. It is represented by the [`Organization`](/docs/reference/javascript/organization) object. To learn about organizations, see the [dedicated guide](/docs/guides/organizations/overview). +Organizations are a flexible and scalable way to manage users and their access to resources within your Clerk application. With organizations, you can assign specific roles and permissions to users, making them useful for managing projects, coordinating teams, or facilitating partnerships. Users can belong to many organizations. One of them will be the [active organization](!active-organization) of the session. It is represented by the [`Organization`](/docs/reference/javascript/organization) object. To learn about organizations, see the [dedicated guide](/docs/guides/organizations/create-and-manage). diff --git a/docs/reference/javascript/types/organization-invitation.mdx b/docs/reference/javascript/types/organization-invitation.mdx index aa5375e4fe..68cbee4d50 100644 --- a/docs/reference/javascript/types/organization-invitation.mdx +++ b/docs/reference/javascript/types/organization-invitation.mdx @@ -81,7 +81,7 @@ The following example demonstrates how to revoke an organization invitation. It It assumes: - you have followed the [quickstart](/docs/js-frontend/getting-started/quickstart) in order to add Clerk to your JavaScript application -- you have [enabled the Organizations feature in the Clerk Dashboard](/docs/guides/organizations/overview#enable-organizations-in-your-application) +- you have [enabled the Organizations feature in the Clerk Dashboard](/docs/guides/organizations/configure#enable-organizations) ```js {{ filename: 'main.js', mark: [22, 23] }} import { Clerk } from '@clerk/clerk-js' diff --git a/public/images/orgs/relationship-diagram.png b/public/images/orgs/relationship-diagram.png new file mode 100644 index 0000000000..2c222e85b1 Binary files /dev/null and b/public/images/orgs/relationship-diagram.png differ