Enabling workspaces (multi-tenancy)

FastStaq ships single-tenant by default, which is the right choice for most products. When you need isolated customer workspaces (teams, organizations), you can turn on multi-tenancy.

When you need it

Enable workspaces when customers should have separate, isolated spaces with their own members and project resources, for example a B2B tool where each company is a tenant. If your product is per-user, you do not need this.

What gets scoped

By default FastStaq keeps billing and credits user-level. Workspace scoping is applied to project resources such as API keys, outbound webhooks, and canned responses. This keeps the common case simple while still isolating tenant data.

Turning it on

Multi-tenancy is gated by a server flag and a matching client flag, which must be flipped together:

# server/.env
MULTI_TENANT=true
# (or the TENANCY_MULTI_TENANT override)

# client/.env (baked at build time)
NEXT_PUBLIC_MULTI_TENANT=true

While the flag is off, the tenant-scope middleware is a no-op. Enabling it activates workspace scoping, per-workspace websocket rooms, and tenant resolution.

Tenant resolvers

Tenants can be resolved by subdomain, header, or JWT (TENANCY_RESOLVERS). Set TENANCY_ROOT_DOMAIN for subdomain routing. Avoid the query-string resolver in production unless you explicitly allow it.

Rollout steps

Enabling tenancy is not just a flag flip in a live system; plan a paired rollout:

1. Turn on the flags in a non-production environment first.
2. Run the schema backfill so existing data is assigned to a default workspace.
3. Roll out the workspace management UI (create/invite/switch).
4. Verify isolation before enabling in production.

Rebuild and redeploy the client because NEXT_PUBLIC_MULTI_TENANT is baked in at build time; restart the API to pick up the server flag.

Related articles

• Roles and permissions (RBAC)
• API keys guide

Still need help?

Open a support ticket before enabling tenancy on a live database.