Model your data

The first step in architecting your application to use Scalekit is mapping your current data model to Scalekit’s core entities. This guide outlines key considerations and approaches for a range of existing data models.

Scalekit’s B2B data model centers on two first-class API entities: Organizations and Users.

Scalekit’s core concepts

Scalekit organizes your application’s data into two main components:

• Organizations represent your application’s tenants or workspaces. They are the core of Scalekit’s multi-tenant architecture. Each organization can contain multiple users who work together.

• Users are the people who access your application. Each user:

  • Has a unique email address within the Scalekit environment.
  • Can belong to multiple organizations.
  • Is automatically linked across organizations when using the same email address.
  • Can have different roles in each organization they belong to.

This structure lets you manage access across different teams while keeping user identities consistent.

Defining your top-level tenant

Your application’s top-level tenant is typically your business customer, who pays for your service and owns all the data and resources within their workspace. This tenant maps directly to Scalekit’s Organization entity. This meta label can be customized to team, workspace, or account to match your product’s terminology.

Key characteristics of a top-level tenant include:

Account ownership

• Manages subscriptions or contract terms
• Controls billing and service-level agreements

Access management

• Controls who can access their organization
• Defines user roles and permissions
• Manages security policies

User management

• Adds and removes users
• Updates user information
• Manages authentication methods

Data segregation

• Keeps data isolated
• Maintains security boundaries
• Ensures data privacy and governance

Organization meta label

You can customize this meta label to team, workspace, or account to match your product’s terminology. Navigate to Scalekit Dashboard > User management > Settings and update the “Organization” meta name.

Extending Organizations

Organizations support custom metadata and external IDs to integrate seamlessly with your existing systems.

Custom metadata

Use custom metadata to store additional information like subscription plans, internal customer IDs, or feature flags. This helps you manage organization-specific configurations within Scalekit and can be included in JWT claims for use in your application.

Metadata

Create a new organization with metadata

curl https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "display_name": "Megasoft Inc",
  "metadata": {
    "invoice_email": "invoices@megasoft.com",
    "plan_type": "enterprise"
  }
}'

External IDs

Use external IDs to link Scalekit Organizations with your existing systems, such as a customer ID from your billing platform. This maintains consistent identification across your infrastructure.

External IDs

Create a new organization with an external ID

curl https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "display_name": "Megasoft Inc",
  "external_id": "CUST-12345-MGSFT",
  "metadata": {}
}'

Map users to Scalekit identities

In Scalekit, a User is a unified profile that can belong to multiple Organizations. While the core user profile is shared, each Organization membership maintains distinct details like roles, status, and metadata. This allows a user to have different roles and permissions in each Organization they are a part of, while maintaining a single identity.

Your approach to mapping users will depend on your current data model.

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

View membership object structure

Memberships example

{
    "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.

Need help with migration?

If your application uses a 1-to-1 model and you’re looking to migrate, please contact us for guidance on the best approach for your use case.

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.

User deduplication

Scalekit uses the email address as the unique identifier for a User within an Environment. This means:

• Two different Users cannot have the same email address within the same 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.

Because of this, you may need to merge duplicate user accounts in your system before migrating to Scalekit. Attempting to create two Users with the same email in the same organization or environment will result in an error.

Linking Scalekit IDs

You should continue to maintain your own user and group tables and link them to Scalekit by storing the organization_id and user_id in your database. You can also store your internal identifiers as external_id or additional metadata fields on the corresponding user objects for a two-way reference.

Refer to User API Add an existing user to an organization and assign them specific roles and permissions.

Work with user profiles Learn about user profile attributes and how to manage user information in Scalekit.