Getting Started with Multi-Tenancy

Adding multi-tenancy to a B2B is foundational if you're building for teams or organizations. You want separate data contexts, scoped permissions, and a seamless experience switching between personal and org-owned content.

Why Multi-Tenancy Matters

Multi-tenancy is one of those architectural decisions that pays off early and compounds over time. A sound identity model enables you to:

1. Separate Data Contexts - Keep organization data isolated from personal data
2. Manage Permissions - Control what members can do within an organization
3. Simplify Billing - Charge organizations rather than individual users
4. Enable Collaboration - Let teams work together seamlessly

Model the Tenant Boundary

Start with an explicit organization identifier on every tenant-owned resource. Never infer tenant scope from a client-provided field alone; derive it from the authenticated session and enforce it in your data-access layer.

type TenantContext = {
  organizationId: string
  userId: string
  permissions: string[]
}

export async function listProjects(context: TenantContext) {
  return db.projects.findMany({
    where: { organizationId: context.organizationId },
  })
}

Create and Switch Organizations

Treat organization creation as a privileged workflow. Create the organization, add the creator as an owner, and establish the active organization in one transaction. When users switch organizations, issue a new session context rather than mutating authorization state in the browser.

Managing Organization Members

Once you've created an organization, invitations should carry a tenant ID, intended role, expiration, and one-time token. Apply role changes on the server and record them in an audit log.

Use broad roles for common workflows, then layer resource-level permissions where the product needs finer control:

• owner: billing, security settings, and destructive organization actions
• admin: members, integrations, and operational settings
• member: day-to-day product access
• viewer: read-only access

Avoid encoding every permission directly into the session. Keep sessions compact and evaluate high-cardinality permissions close to the resource.

Conclusion

Adding multi-tenancy to your application is a crucial step in building a scalable B2B product. With the right tools and architecture, you can create a seamless experience for organizations while maintaining data isolation and security.

Start small with basic organization features, then expand as your users' needs grow. The investment in proper multi-tenancy will pay dividends as your product scales.