Overview of modelling users and organizations

Authenticated users now have access to your app.

Now is the time to consider how you’ll structure your data model for users and organizations. This foundational model will serve you well as you implement features such as workspaces, user invitations, role-based access control, and more—ultimately enabling your application to fully support B2B use cases.

Organizations and Users are the two first-class entities in Scalekit

• An Organization serves as a dedicated tenant within the application, representing a distinct entity like a company or project. A User is an individual account granted access to interact with the application. Typically belong to organization(s).

This is a simplified view of the relationship between these two entities

This model makes it easy to implement essential B2B capabilities in your application.

Flexible user sign-in options for organizations

Configure your application to support multiple authentication methods, allowing users to choose their preferred sign-in options.

Also, this is crucial for enabling organization administrators to set and enforce specific authentication policies for their users.

A primary use case is implementing enterprise Single Sign-On (SSO). This allows your customers to authenticate their users through their organization’s existing Identity Provider (IdP), such as Okta, Google, or Microsoft Entra ID where IdP verifies the user’s identity, granting them secure access to your application.

With Scalekit as your authentication platform, administrators can easily enforce authentication policies for their organization’s users. Scalekit handles this enforcement automatically, either applying organization-specific policies or defaulting to your application’s preferred authentication methods on the login page. Configuring these settings is straightforward—simply toggle the desired options in your Scalekit environment through the dashboard or API.

User records deduplication

Regardless of which authentication methods your users choose, Scalekit automatically recognizes users with identical email addresses as the same individual. This eliminates the need for your application to manage multiple user records for the same person and ensures consistent identity recognition across different authentication flows.

• Two different Users cannot have the same email address within the same Scalekit environment.
• Scalekit automatically consolidates accounts. If a user logs in with an email and password and later uses Google OAuth with the same email, both authentication methods will be linked to the same User record.

On how users join and leave organizations

Control how users join and are provisioned into organizations. Scalekit provides a flexible user provisioning engine to manage the entire user lifecycle.

This includes:

• Sending and managing user invitations.
• Allowing users to discover and join organizations based on their email domain.
• Enabling membership in multiple organizations.
• Securely de-provisioning users when they leave an organization.

These capabilities are built-in, allowing you to deliver a secure and seamless user management experience from day one.

Enforce user roles and permissions

While your product may offer a wide range of features, not all users should have identical access or capabilities. For example, in a project management tool, you might allow some users to create projects, while others may have permission only to view them.

Managing user permissions can be complex. Scalekit simplifies this by providing the necessary roles and permissions your application needs to make authorization decisions at runtime.

When a user completes the login flow, the access token issued by Scalekit contains their assigned roles. Your application can inspect this token to control access to different features. By default, Scalekit assigns an admin role to the organization creator and a member role to all other users, providing a solid foundation for your authorization logic.

Modify user memberships

Scalekit tracks how users belong to organizations through a memberships property on each User object. This property contains an array of membership objects that define the user’s relationship to each organization they belong to.

Each membership object includes these key properties:

• organization_id: Identifies which organization the user belongs to
• roles: Specifies the user’s roles (assigned by your application) within that organization
• status: Indicates whether the membership is active, pending invite or invite expired

The memberships property enables users to belong to multiple organizations while maintaining clear role and status information for each relationship.

{
    "memberships": [
      {
        "join_time": "2025-06-27T10:57:43.720Z",
        "membership_status": "ACTIVE",
        "metadata": {
          "department": "engineering",
          "location": "nyc-office"
        },
        "name": "string",
        "organization_id": "org_1234abcd5678efgh",
        "primary_identity_provider": "OKTA",
        "roles": [
          {
            "id": "role_admin",
            "name": "Admin"
          }
        ]
      },
      {
        "join_time": "2025-07-15T14:30:22.451Z",
        "membership_status": "ACTIVE",
        "metadata": {
          "department": "product",
          "location": "sf-office"
        },
        "name": "Jane Smith",
        "organization_id": "org_9876zyxw5432vuts",
        "primary_identity_provider": "GOOGLE",
        "roles": [
          {
            "id": "role_prod_manager",
            "name": "Product Manager"
          }
        ]
      }
    ],
}

Migrating from a 1-to-1 model

In a 1-to-1 data model, each user is associated with a single organization. The user’s identity is tied to that specific organization, and they cannot belong to multiple organizations with the same identity. This model is common in applications that were not originally built with multi-tenancy in mind, or where each customer’s data and user base are kept entirely separate.

For example, many traditional enterprise software applications like Slack, QuickBooks, or Adobe Creative Suite use this model - each customer purchases their own license and has their own separate user accounts that cannot be shared across different customer organizations.

Migrating from a 1-to-many model

If your application allows a single user to be part of multiple organizations, their profile in Scalekit will also be shared across those organizations. While the user’s core profile is consistent, each organization membership stores distinct information like roles, status, and metadata.

If you already have a membership table that links users and organizations, you can add the Scalekit user_id to that table. When you update a user’s profile, the changes will apply across all their organization memberships.

Aspect	1-to-1	1-to-many
User belongs to	One organization	Multiple organizations
Email address	Tied to one org	Unique across environment
Authentication	Per-organization	Across all orgs
Example apps	Adobe Creative, QuickBooks	Slack, GitHub, Figma
Scalekit use	Simpler setup, less flexibility	Full multi-tenancy capabilities