Multi-tenancy and Stytch's data model

Stytch's B2B SaaS Authentication offers a sophisticated organization-based architecture that enables developers to manage diverse identity requirements across multiple customers or tenants.

This guide explains how Stytch's B2B SaaS Authentication product utilizes an organization-first data model to achieve optimal flexibility and scalability within a multi-tenant authentication system.

On this page, we'll cover the following:

• An organization-first data model
• Stytch Organizations

  • Organization settings

• Stytch Members

  • Account deduplication
  • Member settings and provisioning

• Discoverable organizations and onboarding
• Session exchange and switching organizations

In Stytch's organization-first data model, the Organization object is the core entity around which all other data is organized. Unlike other auth providers, Stytch’s data model uniquely treats organizations as top-level objects, each maintaining its own collection of Member objects.

This approach offers immediate high-level advantages:

• Flexibility: Supports tenant-specific authentication and authorization workflows. It also enables users to create multiple distinct accounts based on membership.
• Scalability: Scales to accommodate growth in both the number and diversity of organizations and users without significant changes to the underlying structure or logic.
• Data isolation: Enforces strong separation of data across different organizations.

Stytch's B2B data model treats Organizations and Members as core data entities.

Stytch's B2B SaaS data model architecture primarily consists of two core API entities:

1. A Stytch Organization is the top-level “tenant", which groups one or more Members together within your application. Each Organization acts as a container for all its tenant-specific auth configurations and access controls and maintains an isolated representation of its membership pool.

2. A Stytch Member is a user who belongs to an Organization. A user can belong to multiple Organizations by having multiple Member records linked together by the same email address.

A Stytch Organization is a top-level “tenant” that manages a collection of Members. In more practical terms, it refers to a group of users who belong together in your application. Most commonly, Stytch Organizations are used to represent businesses and their employees – but they can also represent teams, workspaces, projects, or any other construct your application utilizes to group users together.

Stytch Organizations are uniquely identified by:

1. organization_id: The Stytch-generated unique ID for the Organization.
2. organization_slug: A unique short (typically) human-readable alphanumeric string that you provide. This is often a portion of a login URL (e.g. stytch is the slug in https://ui.honeycomb.io/stytch and https://stytch.slack.com).

As first-class data entities, Stytch Organizations are equipped with a comprehensive set of native admin controls. They can be configured to have their own unique combination of settings for different identity requirements.

Diagram viewJSON view

Stytch's organization-first data model allows developers to manage diverse authentication flows and complex permission settings across various customer organizations simultaneously.

These Organization controls and settings include:

• Approved auth methods: Specify which auth methods can be used for authentication.
• Email domains: Restrict which email addresses Members can sign up with.
• JIT provisioning: Control which auth methods can provision Members upon authentication.
• Invites: Allow or disable invites to join an Organization.
• SSO connections: Manage SSO connections that integrate with IdPs.
• MFA policies: Enforce secondary factor policies.
• RBAC assignment: Assign roles and permissions programmatically to Members.
• Custom metadata: Store application or business-specific attributes on the Organization object.

With feature-rich Organization objects, Stytch effectively streamlines the identity management of each tenant to straightforward API calls. Developers can modify and customize entire auth flows and multiple security settings with a single PUT or POST request on the Organization object.

curl --request PUT \
   --url https://test.stytch.com/v1/b2b/organizations/{ORGANIZATION_ID} \
   -u {PROJECT_ID}:{SECRET} \
   -d '{
         "allowed_auth_methods": ["sso", "magic_link"]
         "auth_methods": "RESTRICTED",
         "mfa_policy": "REQUIRED_FOR_ALL",
         "mfa_methods": "RESTRICTED",
         "allowed_mfa_methods": ["sms_otp"],
         "sso_jit_provisioning": "ALL_ALLOWED",
         "email_invites": "RESTRICTED",
         "email_allowed_domains": ["stytch.com"]
         "trusted_metadata": {
           "billing_tier": "premium",
           "privacy_setting": "private"
         }
       }'

A Stytch Member represents an application user's account within an Organization. Users can belong to multiple Organizations by having multiple Member records, which are linked together by the same email address.

Stytch Members are uniquely identified by:

1. member_id: The Stytch-generated unique ID for the Member.
2. email_address: Stytch also uses the email address to uniquely identify a Member within a given Organization.

Ada has three separate accounts with individualized settings, each represented by a unique Stytch Member record. They all belong to different Organizations, but are linked by the same email address.

Within each Organization, Stytch automatically deduplicates accounts by securely consolidating Member records using the verified email address, even when users log in with different auth methods. Stytch tracks all used auth factors and registers them to the same Member object.

For example, if a user authenticates with Email Magic Links and then with Google OAuth using the same email address, Stytch ensures these actions will result in one canonical Member object rather than two separate, duplicate accounts.

Stytch Member settings include:

• RBAC assignment: Assign default or custom roles and permissions.
• Breakglass: Designate Members who can bypass Organization settings for emergency purposes.
• MFA enrollment: Enroll in MFA and set secondary factor preferences.
• Custom metadata: Store application or business-specific attributes on the Member object.

Stytch also supports three different methods for provisioning and creating Members:

1. Invite: Members can be invited to join a specific Organization by receiving a Email Magic Link invitation.
2. Just-in-time (JIT) provisioning: An Organization can specify trusted sources (such as an Identity Provider or a verified email domain) that enable end users to join the Organization without an explicit invite. Through these sources, Members will be automatically created upon successful authentication.
3. Manual provisioning: Using direct API calls in order to support user base migrations and manual onboarding processes.

With top-level Organization objects, Stytch enables developers to implement a Discovery authentication flow. The Discovery feature allows users to view all their memberships upon logging in once. They can then choose any Organization they wish to authenticate into.

Users log in once to discover all their associated accounts and organizations.

Stytch's Discovery flow also provides users with the option of creating a new Organization for self-serve onboarding.

Additionally, you can use a direct API or SDK call to create a new Organization in order to support manual onboarding processes – often used to restrict access behind a sales team.

With distinct Member records, Stytch unlocks the ability for end users to seamlessly switch between Organizations through session exchange.

This functionality allows an end user to maintain an authenticated state across multiple Organizations without the need for restarted logins, while still enforcing strict multi-tenant boundaries. This capability is particularly useful in applications where users frequently navigate between different organizational contexts and data domains.

Ada can switch between their Organizations and accounts by exchanging Member Sessions.

To support this feature, Stytch leverages a smart session management system that evaluates the auth and security requirements of each Organization. If two Organizations have identical or compatible auth settings, the end user can immediately exchange sessions. If not, Stytch will automatically enforce and prompt the required authentication steps needed to grant an exchanged session for the requested Organization.

With features like session exchange, end users benefit from a flexible yet secure multi-organizational auth system that meets the modern UX needs of SaaS applications.

Read our integration guides to learn more about client-side and sever-side development with Stytch.