# Add multi-tenant workspaces in an afternoon

> Workspaces, membership and roles without designing a tenancy model from scratch or bolting one on later.

- Source: https://www.buildbase.app/guides/multi-tenant-workspaces-in-an-afternoon
- Section: Guides
- Author: Dharmendra Jagodana
- Published: 2026-08-14

## In short

useSaaSWorkspaces gives you workspace creation, switching and membership in one hook, with a WorkspaceSwitcher component for the nav. The part worth getting right on day one is that the workspace, not the user, is the unit that owns data, billing and quota.

[The tenancy decision](/blog/what-is-multi-tenancy) is made early, usually implicitly, and it is expensive to
revisit. Most products start with "a user has data" and discover eighteen months
later that customers wanted "a team has data, and people come and go".

Retrofitting that is a migration across every table you own. If you are
starting from a raw Postgres database, or Firestore, rather than a hook, the
decision does not go away, it just moves earlier - see
[Supabase vs BuildBase](/compare/buildbase-vs-supabase) or
[Firebase vs BuildBase](/compare/firebase-vs-buildbase) for what changes when
you own the schema yourself. And if that raw-database path means isolating
each tenant in its own instance rather than shared tables,
[here's what that isolation costs](/blog/database-per-tenant-cost) as tenant
count grows.

> **Before you start:** A BuildBase project with the SDK installed and authentication working (see
> [BuildBase on Next.js](/guides/buildbase-on-nextjs) or [on
> Vite](/guides/buildbase-on-vite)). This builds directly on whatever auth you
> already have, since membership is a relationship between a user and a
> workspace.

## Step one: get workspaces and switching from one hook

```tsx
import { useSaaSWorkspaces, WorkspaceSwitcher } from '@buildbase/sdk/react';

function App() {
  const {
    workspaces,
    currentWorkspace,
    createWorkspace,
    switchToWorkspace,
    addUser,
    removeUser,
  } = useSaaSWorkspaces();

  return (
    <nav>
      <WorkspaceSwitcher
        trigger={(isLoading, ws) => (
          <button>{ws?.name ?? 'Select workspace'}</button>
        )}
      />
    </nav>
  );
}
```

What you should see: a switcher in the nav listing every workspace the signed-in
user belongs to, and `currentWorkspace` changing as they switch. Membership,
invitations and removal are on the same hook rather than a separate system.

## Step two: make the workspace the unit that owns things

This is the step that decides whether the afternoon was worth it.

[Every row you store should hang off a workspace](/guides/per-org-data-isolation-nextjs), not a user. Every quota should
be checked against a workspace. Every subscription should belong to one. The
metering call in
[charging per API call](/guides/charge-per-api-call-nextjs) takes `workspaceId`
as its first argument for exactly this reason - the meter and the tenant are the
same concept.

The test: if the person who created the account leaves the company tomorrow,
does anything break? If the answer is yes, something is still owned by the user
that should be owned by the workspace.

AgentCenter is the one of ours that leans hardest on this. Its whole model is
multi-project - agents, runs and permissions all hang off a workspace rather
than the person who signed up, and the subscription does too. That was not
foresight. It is the shape you get for free when the workspace is the unit from
the first commit, and the shape you pay a migration for when it is not.

## Step three: roles, before you need them

[Roles](/blog/what-is-rbac) are easier to add now than after customers have data.

```tsx
import { WhenPermission, WhenWorkspaceRoles } from '@buildbase/sdk/react';
```

[Gate on permission rather than role](/guides/roles-and-permissions-per-workspace-nextjs) wherever you can. "Can this person invite
someone" survives a reorganisation of your role names; "is this person an admin"
does not.

> **Tip:** Decide early whether an invited user without an account gets a [pending
> membership](/guides/team-invitations-nextjs) or nothing at all. It sounds like
> a detail and it is the difference between an invite flow that works and one
> that quietly drops people.

## What people get wrong

**One workspace per user, [created silently at signup](/guides/auto-created-first-workspace-nextjs).** It looks simpler and it
means you never build the switcher. Then a customer asks for a second team and
the assumption is baked into every query.

**Billing on the user.** Covered above and worth repeating, because it is the
expensive one.

**Roles as strings in your own tables.** Once permission checks live in your
application code, every new feature needs its own check and they drift.

## Install

```bash
npm i @buildbase/sdk
```
