Architecture scenarios

There are several ways to model how users and organizations fit into your application. The 3 scenarios that will be covered in this guide are:

1. B2C: Business to Consumer
2. B2B: Business to Business
3. Platforms

We will share some of the common characteristics of apps in each scenario as well as the level of support for these features in Clerk.

B2C: Business to Consumer

B2C companies focus on selling products or services directly to consumers. Some popular examples are Netflix, Headspace, and Spotify. Clerk supports the B2C user management model out-of-the-box, with little-to-no configuration.

In a B2C scenario, applications generally share the following characteristics:

• A user creates a single account with your service
• There is a single, shared user-pool which all the users belong to
• Any connections enabled for your application are available to all users to authenticate with
• The application branding is that of your company (as in, not white-labelled per customer or organization)
• The application is accessible under a single domain (for example: example.com or app.example.com)

B2B: Business to Business

B2B companies sell to other businesses. Some examples include: GitHub, Vercel, Salesforce, Sentry, and Clerk.

In the B2B model, multi-tenant SaaS applications generally leverage organizations (sometimes called teams or workspaces) to manage users and their memberships. This approach allows for control over what resources users have access to across different organizations based on their roles.

Oftentimes such applications will also allow users to create personal accounts that are separate from other organizations. For example, GitHub allows users to create repositories under their own personal account or an organization they are part of.

The user pool for multi-tenant, SaaS applications will generally fall into one of two categories:

1. Shared user-pool: the application has a single pool of users. A user can create one account and belong to multiple organizations. The user can have separate roles in each organization.
2. Isolated user-pool: each organization has its own pool of users. A user must create a separate account for each organization.

B2B SaaS applications with the following characteristics are well-supported with Clerk:

• A single application deployment that serves multiple business customers (multi-tenant)
• A shared user-pool model where a user can log in with a single account and belong to multiple organizations
• Enabled connections are available to all users (as in, connections cannot be configured at the organization level)
• The application may carry your own branding or some elements of your customer's branding
• The application is served from a single domain (for example: app.example.com)

Integrating organizations with your application

Clerk offers a number of building blocks to help integrate organizations into your application:

• The <OrganizationSwitcher /> component provides a way for your users to select which organization is active. The useOrganizationList() hook can be used for more control.
• The useOrganization() hook can be used to fetch the current, active organization.
• The <Protect> component enables you to limit who can view certain pages based on their role. Additionally, Clerk exposes a number of helper functions, such as auth(), and hooks, such as useAuth(), to check the user's authorization throughout your app and API endpoints.

The organization's ID should be stored in your database alongside each resource so that it can be used to filter and query the resources that should be rendered or returned according to the active organization.

Platforms

In the Platforms scenario, businesses can create multiple, isolated applications with their own user pools, branding, security policies, and limits. Some examples in this scenario are e-commerce platforms like Shopify, e-learning platforms, and mortgage lending platforms.

For example, you may be creating an e-learning platform that allows universities to create courses and enroll students. In this case, each customer would be a university who would have their own set of students, professors, and administrators as their users. Additionally, each university would likely have a custom domain (courses.example.com) with their branding where their users can authenticate and use the platform.

In the e-learning platform scenario, the users of one university should be completely isolated from another university and each university might have its own set of authentication strategies and security policies.

The following are some of the most commonly requested features for the Platforms scenario (Clerk for Platforms):

• Vanity domains (customer.example.com) or a custom domain (customer.com) for each of your customers
• Allow your customers to independently customize their branding, including their authentication screens, SMS and email templates
• Isolated user pools such that users from one customer are logically separated from users of another customer
• Independently enforce different limits based on your customer's subscription (for example: limit their number of users they can invite to an organization)
• Enable your customers to independently configure the authentication policies, enabled connections, and MFA policies available to their users