Reconciling data models

One of the first things to consider when migrating your application to Stytch is the data model. Designed to address the unique needs of multi-tenant applications, Stytch's B2B SaaS Authentication platform features strong and flexible organization-based data structures. This guide will outline key considerations when reconciling your application's data model and Stytch's.

The first step involves mapping your application's data definitions to Stytch's multi-tenant architecture. Stytch's B2B SaaS data model primarily consists of two first-class API entities: Organizations and Members.

1. A Stytch Organization is the top-level “tenant", which groups one or more Members together within your application.
2. A Stytch Member is an end user who belongs to an Organization. Stytch uses email address as the primary unique identifier for Members within an Organization. An end user can belong to multiple Organizations by having multiple Member records, which are linked together by using the same email address.

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

For more details and technical specifics on Organizations and Members, visit our guide on multi-tenancy or the API reference.

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 end users together.

When mapping your user groups to Stytch Organizations, consider how your existing user groups will translate. Ensure a direct 1:1 mapping that will convert each of your application's user groups into a corresponding Stytch Organization object. Your application's database should store the Stytch organization_id as a column on your user groups tables.

Additionally, you can leverage the following features to tailor a Stytch Organization to meet each user group's needs:

• Custom metadata: Utilize the custom trusted_metadata field on the Organization object to store any application or business-specific attributes for your user groups.
• Authentication and provisioning settings: Configure an Organization's auth settings to control approved authentication methods, allowed email domains, invites, MFA, JIT provisioning, SSO connections, and more.

Refer to the Organization object in the API reference to see all available fields and settings.

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

Next, you need to map your application's users to Stytch Member objects.

Stytch creates a unique Member object for every Organization an end user authenticates into. In other words, an end user who belongs to five different Stytch Organizations will have five separate Stytch Member objects associated with them. Stytch uses the email address to recognize that these Member objects represent the same individual across different Organizations.

Depending on how your application enforces and stores the relationships between users and groups, you will need to create one or many Stytch Member objects for every application user.

If your application only supports single membership for a user record, the data model mapping is relatively straightforward. You only need to create one Member record for each application user record.

With a 1:1 relationship between your user records and organizations, you can store the Stytch member_id as a column directly on your user table.

If your application supports multiple memberships for a user record, you need to create a Member object for every membership that exists in your application.

With a 1:many relationship between your user records and organizations, a more nuanced data mapping is required, like creating a separate table in your database that maps your internal user ids to Stytch member_ids.

Regardless of either scenario, you can leverage the following features to enrich the Stytch Member object:

• Custom metadata: Utilize the custom trusted_metadata and untrusted_metadata fields on the Member object to store any application or business-specific attributes for your end user and their membership.
• Authentication and authorization settings: Configure a Member's auth settings to control MFA enrollment, breakglass privileges, and roles and permissions.

Refer to the Member object in the API reference to see all available fields and settings.

[
  // These three Member objects are all the same end user
  {
    "member_id": "member-test-32fc...",
    "organization_id": "organization-test-07971...",
    "email_address": "adalovelace@stytch.com",
    "email_address_verified": true,
    "name": "Ada Lovelace",
    "status": "active",
    "untrusted_metadata": {
      "job_title": "Engineer",
      "preferred_locales": ["en", "es"]
    }
  },
  {
    "member_id": "member-test-83ei...",
    "organization_id": "organization-test-08264...",
    "email_address": "adalovelace@stytch.com",
    "email_address_verified": true,
    "name": "Miss Ada",
    "status": "active",
    "untrusted_metadata": {
      "timezone": "EST"
    }
  },
  {
    "member_id": "member-test-65yu...",
    "organization_id": "organization-test-02598...",
    "email_address": "adalovelace@stytch.com",
    "email_address_verified": true,
    "name": "Ada",
    "status": "active",
    "untrusted_metadata": {
      "display_theme": "dark"
    }
  }
]

Stytch utilizes the email address as a unique primary key for identifying Members within an Organization. This means two things:

1. Two different Members cannot use the same email address within a single Organization.
2. Stytch will automatically consolidate Members who log into an Organization using the same email address with different auth methods. For example, an end user authenticates into Organization A using Email Magic Links and the email address example@stytch.com. Later, they authenticate into Organization A again with the same email address but this time using Google OAuth. Rather than create duplicate Member records, Stytch consolidates both auth instances under one Member object and member_id.

For this reason, you may need to merge your users' accounts before migrating to Stytch. If your script attempts to manually create two Members in an Organization in Stytch with the same email address, you will receive a duplicate_email error.

Passwords are scoped to an individual Member object within a single Organization. This is unlike email-based auth methods, which can deduplicate and link multiple Members based on the email address. Passwords are unique and cannot be linked between Member objects, even if the Member objects share the same email address and are associated with the same end user.

This is designed to ensure strong multi-tenant separation and to mitigate unintended side-effects. For example, the admin of Org A should be allowed to reset the password of a Member in Org A, but should not be allowed to do so for a Member in Org B.

You should continue to maintain your own internal user and groups tables in your application, and link Stytch’s member_ids and organization_ids in your schema. You can also add your internal identifier references as a trusted_metadata field on the Stytch Member and the Stytch Organization record using metadata.

With an understanding of how your user and organization data model will map to that of Stytch, see our guide to migrate users and organizations to Stytch.