Multi-Tenancy

Multi-tenancy is built into the core, not bolted on. The same APIs work whether you're single-tenant, supporting many tenants in one database, or running each tenant in its own database. You flip a flag rather than re-architect.

The three modes

import { TenantModeEnum } from '@ackplus/nest-auth-contracts';
 
NestAuthModule.forRoot({
  // …
  tenant: {
    enabled: true,
    mode: TenantModeEnum.SHARED,   // or TenantModeEnum.ISOLATED
  },
});

SHARED mode

All tenants live in the same database. Every tenant-scoped table — nest_auth_user_accesses, your Order, your Invoice — carries a tenantId column. Every query the library issues filters by tenant. Every query you write should filter by tenant too.

              ┌──────────────────────────┐
              │       Postgres / MySQL    │
              ├──────────────────────────┤
              │ nest_auth_users           │  (global — same email = same user)
              │ nest_auth_tenants         │
              │ nest_auth_user_accesses   │  (user × tenant × roles)
              │                           │
  Tenant A ──▶│ orders   tenantId='A'…    │
  Tenant B ──▶│ orders   tenantId='B'…    │
              └──────────────────────────┘

Pros

• One database, one connection pool, simple ops.
• Cross-tenant queries trivially possible (super-admin views, support reports).
• Cheap to spin up a new tenant — one INSERT into nest_auth_tenants.

Cons

• A bug in your tenant-filter query is a data-leak vulnerability. Use the request context consistently and write a repository wrapper that filters automatically if you can.
• Noisy-neighbour: a heavy tenant slows queries for everyone.
• Hard to satisfy compliance regimes that require physical isolation.

Where to filter by tenantId

import { CurrentTenantId, Auth } from '@ackplus/nest-auth';
 
@Auth()
@Get()
list(@CurrentTenantId() tenantId: string) {
  return this.orders.find({ where: { tenantId } });
}

The tenantId decorator reads from the AsyncLocalStorage-backed request context. The library populates it automatically based on the active session's tenant.

ISOLATED mode

What ISOLATED actually does: it scopes identity per tenant, in a single database. The same email is a distinct account per tenant — alice@x in tenant A and alice@x in tenant B are two different users with two different password hashes, sessions, and role sets. Account uniqueness is (user, tenantId); the library looks users up as getUserByEmail(email, tenantId). Because an account belongs to exactly one tenant, switchTenant is disabled in ISOLATED mode — to act as a different tenant you sign in to that tenant directly.

              ┌───────────────────────────────────────┐
              │            Postgres / MySQL            │
              ├───────────────────────────────────────┤
              │ nest_auth_tenants                      │
              │ nest_auth_users     (alice@x in A)     │  ← two DISTINCT
              │ nest_auth_users     (alice@x in B)     │     user rows
              │ nest_auth_user_accesses (user×tenant)  │
  Tenant A ──▶│ orders   tenantId='A' …                │
  Tenant B ──▶│ orders   tenantId='B' …                │
              └───────────────────────────────────────┘

This is logical isolation (one database, tenant-scoped identity), which is what most "each customer is a separate org/property" apps need. Contrast with SHARED, where the same email is the same user who can belong to many tenants via nest_auth_user_accesses.

Logging in requires a tenantId — see Logging in under a tenant (ISOLATED). And because the same email can be several accounts on one device, ISOLATED pairs naturally with the account switcher.

The library does NOT switch databases for you. There is no per-tenant data-source/connection routing built in — IsolatedTenantContextService only resolves the active tenantId; it does not select a TypeORM DataSource. If you need physical per-tenant databases (separate connections/schemas for compliance), you wire that yourself (e.g. a request-scoped DataSource keyed by tenantId); the library gives you the tenant id on the request context to drive it.

Pros

• Strong logical separation — accounts and identities never cross tenants; the same email in two tenants is genuinely two accounts.
• Simple ops — still one database and one connection pool.

Cons

• Not physical isolation by itself — if you need separate databases for compliance, you add the data-source routing.
• A new account must be created per tenant (no implicit cross-tenant membership; that's SHARED's model).

Tenant context — how it gets resolved

Every authenticated request carries an active tenant. The library resolves it in this order:

1. JWT claim — the access token carries tenantId (set when the session was created).
2. switchTenant action (SHARED only) — explicit tenant switch via POST /auth/switch-tenant rotates the session. Disabled in ISOLATED.
3. Default tenant fallback — if defaultTenantOptions is configured and the user has no other tenant, the library puts them in the default.

At login the tenant is resolved differently — before there's a session: in ISOLATED you pass tenantId on the login/signup/forgot-password request (it's how the same email is disambiguated; the lookup is tenant-scoped). Use GET /auth/tenants/lookup?slug= to turn a human-friendly slug into the tenantId for the login form. See Logging in under a tenant (ISOLATED).

The resolved value lands on the request context and is what every @CurrentTenantId()-style decorator reads.

Default tenant

For apps that are "really single-tenant but might add tenants later":

NestAuthModule.forRoot({
  tenant: { enabled: true, mode: TenantModeEnum.SHARED },
  defaultTenantOptions: {
    name: 'My App',
    slug: 'default',
    isActive: true,
  },
});

The library auto-creates this tenant on first boot and assigns new signups to it (in registrationHooks.onSignup). You can flip tenant.enabled to false later if you decide tenancy was overkill.

Creating tenants programmatically

Use TenantService:

import { Injectable } from '@nestjs/common';
import { TenantService, NestAuthEvents, TenantCreatedEvent } from '@ackplus/nest-auth';
 
@Injectable()
export class OnboardingService {
  constructor(private readonly tenants: TenantService) {}
 
  async createWorkspace(name: string, ownerId: string) {
    const tenant = await this.tenants.create({
      name,
      slug: slugify(name),
      isActive: true,
      metadata: { plan: 'free' },
    });
 
    // Add the owner as the first member with the admin role
    await this.userAccess.assign({
      userId: ownerId,
      tenantId: tenant.id,
      roleNames: ['admin'],
      isDefault: true,
    });
 
    return tenant;
  }
}

The TenantCreatedEvent fires automatically — wire your billing system, Slack notification, default-data seeder, etc. to the event listener:

@OnEvent(NestAuthEvents.TENANT_CREATED)
async onTenantCreated({ tenant }: TenantCreatedEvent) {
  await this.billing.createCustomer({ tenantId: tenant.id, name: tenant.name });
  await this.seedTemplates(tenant.id);
}

Switching tenants

A user can belong to multiple tenants — the nest_auth_user_accesses table stores the membership. Switching is one call:

await client.switchTenant({ tenantId: 'tenant-acme' });

The server issues a fresh session bound to the new tenant; the client persists the new tenantId; React's useUser() re-renders with the new context. The tenant-switcher recipe shows a complete dropdown UI.

Roles per tenant

A user's roles are tenant-scoped by default. Alice can be admin in tenant A and member in tenant B. The NestAuthUserAccess row holds the per-tenant role assignment.

For roles that span all tenants — global admins, support staff — use Platform Access instead.

Multi-platform / guard pattern

A common production pattern is one backend serving several frontends — an admin console, a tenant-facing portal, a mobile app. Each frontend should only allow login from users with a role on its guard, even if the same backend serves them all.

NestAuthModule.forRoot({
  tenant: { enabled: true, mode: TenantModeEnum.SHARED },
  roleGuards: ['ADMIN', 'PORTAL', 'FRONTEND'],
 
  platformAccess: {
    enabled: true,
    validate: async (request) =>
      request.headers.origin?.includes(process.env.ADMIN_URL!) ?? false,
  },
 
  loginHooks: {
    onLogin: async (user, input, ctx) => {
      // Detect which app the user is logging in on (from origin or x-platform header)
      const requiredGuard = detectGuardFromRequest(ctx.request);
 
      const roles = ctx.platformAccess?.roles ?? ctx.userAccess?.roles ?? [];
      const ok = roles.some((r) => r.guard === requiredGuard);
      if (!ok) {
        throw new UnauthorizedException({ code: ERROR_CODES.INVALID_CREDENTIALS });
      }
    },
  },
});

This is documented in detail in the multi-platform login recipe.

Where tenancy lives in the schema

Decorators

Related

• User Access & Platform Access — per-tenant vs cross-tenant roles.
• RBAC — roles, permissions, multiple guards.
• Logging in under a tenant (ISOLATED) — slug → tenantId, the login DTO, password reset.
• Multi-account login & switching — several ISOLATED accounts on one device.
• Tenant switcher recipe — SHARED-mode tenant switching.
• Multi-platform login recipe.
• TenantService reference.