> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agent-auth`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# 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

![](@/assets/docs/fsa/model-your-data/1-k.png)

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.

```d2
direction: right

# Define entities
User 1: "john.doe@gmail.com"
User 2: "mary.jane@company.com"
Your App.Scalekit: "Scalekit"
Organization 1: "Customer Org 1"
Organization 2: "Customer Org 2 \n (Enforces SSO)"

# Define authentication flows
User 1 -> Your App.Scalekit: "Email Magic Link"
User 2 -> Your App.Scalekit: "SAML/OIDC SSO"

# Define login actions
Your App.Scalekit -- Organization 1: "Authenticates to"
Your App.Scalekit -- Organization 2: "Authenticates to"

# Add annotations
# Authentication Methods:
# Magic Link:
```

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](/authenticate/fsa/complete-login/#decoding-token-claims), 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.

```json
{
    "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 |

---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |