Data Modeling Practices for Building Multi-Tenant B2B Apps with WorkOS Organizations

Multi-tenant architecture is a core concern for B2B SaaS products. How do you serve multiple enterprise customers from a single application while ensuring data isolation and clear permissions? WorkOS Organizations offers an officially recommended mapping approach. This article draws on the official guide to outline the key design decisions for implementing a multi-tenant B2B application in Next.js.

Core Principle: Organizations Belong to WorkOS, Workspaces Belong to You

The design philosophy behind WorkOS Organizations is clear: let Organizations represent your customers (i.e., the paying enterprise entities), not the teams, projects, or workspaces within those customers. Each Organization corresponds to an enterprise account, carrying identity-related data such as its members, SSO connections, and directory sync.

The "workspace" that truly belongs to the business layer should stay in your own database. This is the most critical division of labor in the entire approach. The reason: workspaces typically contain a great deal of business logic — project configuration, billing dimensions, role rules, data partitioning strategies — and these should not be bound to an external identity service. By modeling workspaces as your own entities, you can freely evolve their structure without worrying about WorkOS data model constraints.

A single Organization can correspond to multiple workspaces, or it can be a one-to-one relationship, depending on your product shape. But the mapping must be explicitly stored in your own database, typically by adding a workos_organization_id foreign key to the workspace table.

What is WorkOS: WorkOS is a developer platform for B2B SaaS that provides APIs for enterprise-grade identity features, including SSO (single sign-on), SCIM directory sync, audit logs, and the Admin Portal. Its core value lies in enabling SaaS teams to support the login and account lifecycle management required by large customers' IT departments without building their own adaptation layer for enterprise identity protocols like SAML, OIDC, and OAuth.

The Organizations object: In the WorkOS data model, Organization is the top-level container for a tenant, carrying identity-related data such as member lists, SSO connections, Directory Sync directories, and domain verification. It is linked to your application through workos_organization_id. Understanding this is crucial: WorkOS is only responsible for "which enterprise this user belongs to and how to prove their identity," while "what business objects this user can operate on within the enterprise" is entirely determined by your own authorization model. This boundary of responsibility is the foundation for all the design decisions that follow in this article.

Organization Switching: Current Organization Context in the Session

A user may belong to multiple Organizations simultaneously — for example, a freelancer serving three companies at once, or an enterprise IT admin who needs to operate across multiple subsidiaries. The application must be able to clearly know "which organization the current request belongs to."

The recommended approach is to maintain a current_organization_id in the user session. After a user logs in, if they have membership in multiple organizations, display an organization selector; the selected organization ID is written to the session, and all subsequent database queries use it as a filter condition. Organization switching is essentially updating this session field, not re-authenticating.

In Next.js, this context can be injected through middleware or server components. Every database operation must carry the organization ID as the basis for tenant isolation — this is the first line of defense against cross-tenant data leakage. Remember: do not rely solely on the organization ID passed from the frontend; the server must verify that the current user actually belongs to that organization.

Session mechanism: In Next.js, sessions are typically implemented through encrypted cookies (such as Auth.js/NextAuth's JWT session or database session). Storing current_organization_id in the session rather than in the URL or local state has the advantage that server-side rendering, Server Actions, and Route Handlers can all read it directly without trusting parameters passed in from the client. Switching organizations requires only a single server-side operation to update the session, without going through the authentication flow again.

Enforcing tenant filtering: A common approach to multi-tenant isolation is to make organization_id a foreign key column on every business table and uniformly inject the filter condition at the data access layer — for example, using Prisma middleware, Drizzle's RLS policies, or relying directly on PostgreSQL's Row Level Security (RLS). If filtering is only done in the frontend or in a single query, a single missed spot can lead to cross-tenant data leakage, so setting up RLS at the database layer as a last line of defense is recommended.

Cross-Tenant Guests: Modeling External Collaborators

In B2B scenarios, it's common for external parties to need access to specific resources — consultants, auditors, and partners of the customer company. Such "cross-tenant guests" should not be added to the customer's Organization, otherwise they would gain excessive permissions within that organization's scope.

A safer approach is to introduce a resource-level sharing mechanism in your own data model. Guests gain access to a specific workspace or document through an invitation link or explicit authorization, and their identity remains that of an independent user, just granted restricted, fine-grained permissions. WorkOS handles authenticating who this user is, while "what they can see" is entirely determined by your authorization logic.

This design avoids polluting the organization member list with external parties and makes permission auditing clearer: organization members are formal members, and guests are explicitly authorized exceptions.

Internal Administrators: Platform-Side Cross-Organization Access

Your own operations, support, and engineering teams need to access data across all organizations to troubleshoot issues or provide support. Such internal administrators should not be stuffed into each customer's Organization — that would pollute the customer's organization member data and also pose security risks.

The recommended approach is to establish an independent platform administrator role system, decoupled from WorkOS Organizations. Internal administrators log in through your own admin backend and have cross-organization read permissions, but all operations should be strictly audited and logged. If operating as a customer is genuinely necessary, use the impersonation capability provided by WorkOS, and ensure such operations are clearly flagged and recorded.

Completely separating internal permissions from customer permissions is the most easily overlooked yet most important part of a multi-tenant system's security model.

Impersonation: The impersonation capability provided by WorkOS allows platform-side personnel to briefly log in as a certain user to reproduce issues reported by customers. When using it, follow the principles of least privilege and traceability: clearly record the operator, the impersonated user, the time, and the reason, and prominently indicate in the interface that impersonation is currently active to avoid accidental operations on real customer data. Impersonation sessions should have a short validity period and be traceable through audit logs.

Implementation Checklist

When actually implementing this, the following decision points are worth confirming one by one: whether the mapping between Organizations and workspaces is one-to-one or one-to-many; how the organization context in the session is securely passed; where the permission boundary for cross-tenant guests is drawn; whether internal administrators have an independent permission channel; and whether all database queries use the organization ID as a mandatory filter condition. Once you've thought through these questions clearly, the skeleton of your multi-tenant B2B application is in place.

One-line Summary

WorkOS Organizations multi-tenant modeling: Organizations belong to the platform, workspaces belong to you, and isolation relies on sessions and organization IDs.

Paragraph Summary

This article draws on the official WorkOS Organizations guide to outline the key design decisions for implementing a multi-tenant B2B application in Next.js. The core principle is separation of responsibilities: WorkOS's Organization represents the paying enterprise customer, carrying identity data such as members, SSO, and directory sync; business-layer workspaces (project configuration, billing dimensions, role rules, etc.) remain in your own database, explicitly linked through a workos_organization_id foreign key. The article further provides approaches for handling four types of role boundaries: regular users switch organizations through current_organization_id in the session, and the server must verify membership; cross-tenant guests use resource-level sharing rather than joining the customer's Organization; internal administrators should establish an independent platform permission system decoupled from customer organizations, using WorkOS's impersonation capability when necessary. Finally, it emphasizes that all database queries must use the organization ID as a mandatory tenant isolation condition.