Overview

Organizations let you build teams and multi-tenant SaaS out of the box, which is a widely used pattern, especially in a B2B apps. Users can create organizations, invite teammates, assign roles, and seamlessly switch between workspaces.

What is multi-tenancy?

Multi-tenancy is a software architecture pattern where a single instance of an application serves multiple tenants, each with its own data and configuration.

The feature is mostly powered by the Better Auth organization plugin and integrates with TurboStarter's API, routing, data layer, and UI components. This allows you to share most of the code between the web app, mobile app, and extension.

Architecture

TurboStarter uses a pragmatic multi-tenant architecture:

Tenant context lives in the session as the active organization ID (derived from the user's selection or defaults). Server handlers read this context to enforce scoping.
Data scoping is performed via organizationId on tenant-owned tables and guard clauses in queries. Background tasks and API routes receive the same context.
Authorization combines tenant scoping with role checks. We separate “can access this tenant?” from “can perform this action within the tenant?”.
Extensibility: add new tenant-bound entities by including organizationId and using the provided helpers to read the active organization.

This keeps data isolated per organization while remaining simple to reason about and customize.

You can restrict who can create organizations, perform actions within it, and hook into lifecycle events using our API.

Check dedicated Data model, RBAC and Invitations sections or direct Better Auth docs for more details.

Concepts

To effectively use multi-tenancy in your app, we introduced a few core concepts that define how the whole system works:

Concept	Description
Organization	A workspace that owns resources and settings, acting as an isolated tenant.
Member	A user assigned to an organization.
Role	Access level within an organization (see RBAC).
Invitation	Email request to join an organization (see Invitations).
Active organization	The currently selected organization in a user's session, used to scope data and permissions.

These concepts provide the building blocks for flexible team management and secure, multi-tenant SaaS applications.

Development data

In development, TurboStarter automatically seeds some example data when you setup services:

One organization is created by default.
All default roles are created and assigned within that organization.
Sample invitations are generated so you can test the invite flow.

You can safely experiment with these sample organizations, roles, and invitations to understand multi-tenancy features - reset or reseed anytime to return to the default state.

The default credentials for demo users can be customized using the SEED_EMAIL and SEED_PASSWORD environment variables.

Never run in production

The default development data and setup are intended for local development and testing only. Never use these seeds or configurations in a production environment - they are insecure and may expose sensitive functionality.

Customization

You have flexibility to adapt organizations to fit your product. For example, you might rename labels (such as Organization to Team or Workspace), and update the UI copy accordingly.

You can adjust the available roles and permissions to suit your access model.

The invitation flow can be customized, including how verification, onboarding, or metadata capture work.

You may also want to introduce tenant-specific policies, like usage limits, feature flags, or billing rules.

Feel free to check how to configure all of these features in the dedicated sections below.

Data model

Entities and relationships for organizations and multi-tenancy.

Active organization

Set and switch the current organization context within your application.

RBAC (Roles & Permissions)

Manage roles, permissions, and access scopes.

Invitations

Send, track, and accept organization invites.