Stytch B2B Basics

Stytch’s B2B auth product is built around two core entities: Organizations and Members.

Data model relationship between Organizations and Members.

Represents an instance or tenant in your application, typically mapping to each of your top-level customers.

Key characteristics of a top-level customer are:

• Account Ownership: the tenant holds the subscription or contract for using your services, or has the ability to manage billing and upgrade if you have a free tier
• Access Management: the tenant determines which end users can access their instance, and what roles and permissions authorized end users can do within the context of the tenant
• User Management: the tenant can manage end users, performing admin actions like updating emails or resetting MFA enrollment
• Data Segregation: the data and configurations that belong to the tenant are typically isolated from other tenants, ensuring strong governance and security

In most standard B2B use cases this is a shared workspace managed and paid for by a company and accessed by their employees. If you have a mix of business customers and individual end users, we recommend creating an Organization behind the scenes for each individual user "tenant" in order to allow these single-player accounts to seamlessly upgrade and add collaborators in the future. This is the same approach that Notion takes, creating a WorkspaceID in the background for both single-player and multi-player sign-ups.

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

Represents an individual end user’s account within a given Organization, identified by their email address.

While emails are unique within the Organization, an end user can belong to multiple Organizations under the same email, each being represented as a distinct Member record.

This model allows each Organization to have complete control over all the users who access their instance, from mandating particular primary or secondary auth methods, to admin updates to their profile information and identifying email.

End users who are part of multiple Organizations can easily switch between them without logging out and logging back in, and Stytch will enforce that all authentication requirements of each Organization are satisfied.

Stytch Members are uniquely identified by:

1. member_id: Across all Organizations, Members are uniquely identified by the Stytch-generated MemberID
2. email_address: Within the Organization, Members can also be uniquely identified by their email address

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.

Stytch offers a comprehensive set of Organization admin controls, allowing your customers to configure the specific settings they need to meet their unique identity, security and compliance requirements.

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

[
  {
    "organization_id": "organization-test-07971b...",
    "organization_name": "Organization A",
    "organization_slug": "org-a",
    "trusted_metadata": {
      "billing_tier": "free",
      "privacy_setting": "public"
    },
    "email_invites": "ALL_ALLOWED",
    "email_jit_provisioning": "RESTRICTED",
    "email_allowed_domains": ["stytch.com"],
    ...
  }, 
  {
    "organization_id": "organization-test-02645e...",
    "organization_name": "Organization B",
    "organization_slug": "org-b",
    "trusted_metadata": {
      "billing_tier": "premium",
      "privacy_setting": "private"
    },
  	"email_invites": "RESTRICTED",
    "email_allowed_domains": ["stytch.com"],
    "allowed_auth_methods": ["sso", "passwords"],
    "mfa_policy": "REQUIRED_FOR_ALL",
    "sso_jit_provisioning": "ALL_ALLOWED",
    ...
  },
  {
    "organization_id": "organization-test-09320h...",
    "organization_name": "Organization C",
    "organization_slug": "org-c",
    "trusted_metadata": {
      "billing_tier": "enterprise",
      "privacy_setting": "private"
    },
    "auth_methods": "RESTRICTED",
    "allowed_auth_methods": ["sso"],
    "sso_jit_provisioning": "NOT_ALLOWED",
    ...
  }
]

These Organization controls and settings include:

• Approved auth methods: Allows an Organization to specify which primary auth method(s) their members can use to log in (e.g. SSO only, or either Google OAuth and Email Magic Link)
• Just-in-Time (JIT) Provisioning: Optionally allow end users who meet the Organization's JIT Provisioning sources (email domain, SSO, or OAuth tenant) to automatically create an account without being explicitly added
• Invites: Option to allow invites to any email domain, restrict to just Allowed Domains, or to disable entirely
• SSO connections: Configure multiple SSO connections to have members authenticate via their workforce IdPs, with JIT Provisioning and automatic role assignment per-Connection.
• MFA policies: Enforce that all members perform MFA in order to log into the Organization, and specify which MFA methods are allowed (e.g. TOTP only)
• RBAC assignment: Assign roles and permissions to members either directly or automatically, based on SCIM Group membership, SSO Connection, or email domain.
• Custom metadata: Store application or business-specific attributes on the Organization object.

Stytch Member settings include:

• RBAC assignment: Members can be assigned multiple Roles within an Organization, either directly or automatically based on their SCIM Group membership, email domain, or the SSO Connection they logged in with.
• Breakglass: Designate Members who can bypass the Organization's primary authentication requirements for maintenance purposes, in order to ensure Organizations can always self-serve address issues with their configuration.
• MFA enrollment: Enroll in MFA and set secondary factor preferences, even if the Organization does not require MFA.
• Custom metadata: Store application or business-specific attributes on the Member object.

Stytch also supports four 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. Pending invites will be shown to the user in the Discovery flow, making it easy to find and join the Organization even if they miss the invite email
2. Just-in-time (JIT) provisioning: If an end user meets the JIT Provisioning requirements of an Organization, these Organizations will be shown in the Discovery flow, ensuring that new sign-ups can easily find and join their teammates
3. SCIM: Organizations can programmatically provision, deprovision and update their Members directly from their workforce IdP by setting up a SCIM Connection. Stytch will automatically make all updates requested by the IdP via SCIM, ensuring seamless and instantaneous access management at scale
4. Manual provisioning: Using direct API calls in order to support user base migrations and manual onboarding processes.

Discovery refers to the flow where an end user authenticates before specifying the Organization they wish to access, and is then presented with all of the Organizations that they are:

• Currently an active Member of
• Have a pending invite to join
• Are eligible to join based on their email domain

The end user then selects the Organization they wish to log into, or can alternatively opt to create a new Organization.

When selecting an existing Organization, Stytch will enforce that the Organization’s authentication requirements have been met – and if not, prompt the end user to perform MFA or use a different primary auth method – before logging the user in and returning a Member Session.

This flow allows you to have a centralized login page for all Organizations, and ensures that end users are able to find any existing instances they have access to, instead of accidentally creating a new one. This often helps improve conversion by centralizing a company’s usage of your tool in a single instance, allowing for better collaboration and clearer value prop.

Organization-specific login refers to the flow where end users go to a specialized login page for their tenant, often a subdomain or route that contains the Organization Slug (e.g. acme-corp.yourapp.com or yourapp.com/team/acme-corp).

The end user will be presented with the specific authentication methods the Organization allows, and can log into the Organization directly if they are:

• Currently an active Member of
• Have a pending invite to join
• Are eligible to join based on their email domain or the SSO Connection that they authenticated through

We recommend using this flow alongside discovery to support enterprise customers with SSO configured.

However, if your app does not already have tenanted subdomains or routes, Stytch also supports IdP-initiated SSO – which allows end users to simply initiate login to your app directly from their company’s workforce Identity Provider (IdP), skipping the discovery flow.

Organization Switching, or Session Exchange, refers to the flow of allowing end users to switch between various Organizations they belong to, without needing to log out and log back in.

While Stytch Sessions are explicitly scoped to a specific Member within an Organization, eliminating any ambiguity around the context that the end user is operating within and their permissions within that context, we offer out-of-the-box support for:

• Surfacing any other Organizations the end user belongs
• Prompting for additional step-up authentication if needed to switch to the selected Organization
• “Exchanging” their current Member Session for a new Member Session on the selected Organization

This model allows seamless switching between multiple Organizations, while still maintaining the data isolation and authentication requirements that your enterprise customers demand.

Our B2B product is purpose built around the unique dynamics of having companies as customers – where each one of those companies wants full control of who can access their instance of your app, how those users must authenticate, and what they can do once they’re logged in. By centering our data model and product around this organization-driven ownership and control, we allow you to easily satisfy the full range of authentication and authorization features required to serve customers of every size – from the enterprise requirements of Fortune 100 companies, to powering PLG and prosumer motions.

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

Stytch offers developers a comprehensive set of features and capabilities in order to build secure and scalable B2B SaaS Authentication.

This is a non-exhaustive list of features that includes but is not limited to:

• Multi-tenancy: Stytch's B2B SaaS Authentication platform is built upon two key data entities: Organizations and their Members. With Stytch, you can implement B2B SaaS Authentication without needing to build all the back-end logic to solve the many challenges that multi-tenancy poses like per organization settings, authentication settings, invites, provisioning, multiple memberships, account deduplication, and more.

• Organizations: Stytch treats Organizations as first-class entities. Every Organization has configurable settings for administering important access controls like allowed auth methods, allowed email domains, provisioning, invites, IdP connections, and more. Organizations can have thousands or just one single Member, making it flexibly suited for enterprises, teams, and collaborative data models. Refer to the Organization settings guide to learn more.

• Members: Stytch stores and manages authenticated end users as Members who are primarily identified by their email addresses. A single end user can have multiple distinct Members in different Organizations linked by the same email address.

• Single Sign On: Stytch supports both SAML and OIDC protocols for SSO login. Integrate with IdPs for centralized authentication with existing identity systems and frameworks. Organizations can support multiple SSO connections with different IdPs and specify which connections can be used as defaults or for JIT Provisioning. Refer to the Single Sign On guide to learn more.

• Sessions: Stytch issues, stores, and validates Sessions on behalf of your application. After an end user successfully authenticates, Stytch's API will return both a session_token and a session_jwt for you to store and manage. Use Stytch's Sessions to validate requests, authorize actions, and store metadata.Refer to the Sessions guide to learn more.

• Auth methods: Stytch offers a comprehensive suite of authentication methods. Choose the right login experience for your application user base. We offer Email Magic links, Passwords, Single Sign On, and OAuth for primary authentication, and offer One-Time Passcodes (OTP), and Time-Based One-Time Passcodes (TOTP) for MFA.

• Break glass: Members can also be designated as breakglass which grants them elevated privileges in the Organization for use cases such as emergency access. Refer to the Member API object to learn more.

• RBAC: Stytch's RBAC framework is an authorization model that governs resource access within your application. The RBAC model streamlines the management and enforcement of permissions with a flexible interface designed for a multi-tenant auth system. Refer to the Member API object to learn more.

• SCIM: Stytch's SCIM solution offers a way to integrate with workforce identity providers for automated user provisioning. Developed to streamline identity management processes, SCIM provides a common framework for handling user data synchronizations within complex, multi-domain environments. Refer to the SCIM guide to learn more.

• Webhooks: Subscribe to webhook events for updates that occur out-of-band from your system, such as provisioning and deprovisioning through SCIM or updates from the Stytch Dashboard. Refer to the Webhooks guide to learn more. Refer to the Webhooks guide to learn more.

• Multi-Factor Authentication: Stytch supports MFA. Organizations and Members can opt-in to MFA and add an extra layer of security by requiring multiple forms of verification factors during the authentication process.Refer to the MFA guide to learn more.

• Device Fingerprint-Protected Auth: Protection from account takeover (ATO) and related attacks using Device Fingerprinting on every authentication request. Refer to the DFP Protected Auth guide to learn more.

• Protected Email Magic Links: Ensure the delivery of email magic links even when enterprise security services are in place to check links. Refer to the Protected Email Magic Links guide to learn more.

• Just-in-time (JIT) provisioning: Organizations 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 when an end user successfully authenticates.

• Discovery: Stytch's Discovery flow enables end users to discover all of their Organizations upon authentication. Instead of logging in to each Organization separately, the end user can use the Discovery flow to log in once, see all of their memberships, and select an Organization to authenticate into. Discovery also allows end users to switch between Organizations within an active Session. Refer to the core flows overview above to learn more.

• Enterprise onboarding: Stytch supports manual onboarding processes, often used to restrict access behind a sales team (e.g. Lattice), by exposing direct API calls to create Organizations. Refer to the Create Organization API endpoint to learn more.

• Self-onboarding: Stytch also supports end users being able to create Organizations, often used for self-service onboarding flows (e.g. Slack). This can be done by creating an Organization and initial Member as the final step of the Discovery flow. Refer to the core flows overview above to learn more.