# 28 - Multitenancy > **Status:** Draft (design proposal — nothing here is implemented). This document defines the target > architecture for operating OpenWA as a multi-tenant platform: tenant identity, access control, 2FA, > per-tenant branding, isolation, quotas, and the migration path from today's single-operator model. ## 28.1 Goals & non-goals **Goals** - One OpenWA deployment safely hosts many independent organizations (tenants), each with its own WhatsApp sessions, users, API keys, branding, plugins, and data — with no cross-tenant visibility. - Enterprise-grade identity: named users with per-tenant roles and optional/enforced two-factor authentication (TOTP), alongside the existing API-key model for programmatic access. - A migration path where today's single-tenant installations keep working unchanged (everything lands in a default tenant). **Non-goals (explicitly out of scope for the first phases)** - Billing, seat management, and subscription metering. - Per-tenant database servers or per-tenant process isolation (see the isolation decision in 28.4). - Public self-service tenant signup (tenants are provisioned by a platform admin). ## 28.2 Current state assessment OpenWA today is **multi-session, not multi-tenant**. What already exists and is reused by this design: | Primitive | Where | Reuse | | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Many WhatsApp sessions per deployment, engine-isolated | `session.service.ts` | Sessions become tenant-owned resources | | API keys with roles (`ADMIN/OPERATOR/VIEWER`) and an `allowedSessions` scope; list + stats already scope-filtered | `api-key.entity.ts:37`, `api-key.guard.ts:64-77`, `session.controller.ts:68-70` | Evolves into tenant-scoped keys; the enforcement pattern (guard-level session resolution) is exactly where tenant checks plug in | | Per-session plugin activation and per-session config overrides | `sessionConfig` in the plugin loader | Per-tenant plugin policy on top | | All business data keyed by `sessionId` | messages, audit_log, webhooks, templates | Adding `tenantId` alongside is mechanical | | Per-request ALS actor stamping (audit attribution) | `request-context.ts` | Audit gains `tenantId` at the same point | **The gaps** (what makes it not multi-tenant today): no tenant entity, no named users or memberships, dashboard identity is the API key itself, all branding is global (engine device name, dashboard theme/logo/title), storage/backups/quota are global, and there is no tenant-scoped audit boundary. ## 28.3 Definitions & mental model - **Platform admin** — operates the deployment (today's `ADMIN` key owner). Provisions tenants, never reads tenant message content by default (see 28.14). - **Tenant** — an organization. Owns sessions, users, API keys, plugins-activation, branding, quotas, and a data partition. Identified by `tenantId` (uuid) + a stable `slug`. - **Membership** — a named **user**'s relationship to a tenant, with a **tenant role** (`owner`, `admin`, `operator`, `viewer`). One user may belong to many tenants. - **Tenant role vs platform role** — today's global `ApiKeyRole` becomes the _platform_ role; the tenant role governs what a user/key may do _inside_ one tenant. The full matrix is in 28.5.3. Everything tenant-owned carries `tenantId`: sessions, API keys, users (via memberships), plugin activations, webhook endpoints, templates, and every row derived from sessions (messages, audit, search indexes are recomputed from the `sessionId → tenantId` mapping, so no per-row backfill of message tables is required). ## 28.4 Isolation architecture (decision) Chosen: **shared database, `tenantId` on every tenant-owned row, enforced at the service/guard boundary** — the same boundary that already enforces `allowedSessions` today. | Option | Verdict | Why | | --------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Row-level (`tenantId` columns, shared schema) | **Chosen** | Matches the existing `sessionId` pattern, zero-infra migration, per-tenant backup/filtering still possible, and PostgreSQL RLS remains a later hardening option | | Schema-per-tenant (Postgres) | Later option | Real isolation at the DB layer, but migrations × N tenants and cross-tenant platform tables get awkward; revisit if a customer contract demands it | | Database-per-tenant | Rejected for now | Operational complexity (migrations, pooling, backup orchestration) buys little at this scale | Hard rule: **no query returns rows without a tenant predicate**. The guard resolves the tenant context once per request (from key/user + route session) and the service layer composes with it — mirroring how `allowedSessions` is enforced in `ApiKeyGuard` and `SessionService.findAll` today, so there is one chokepoint to audit instead of a filter remembered per query. ## 28.5 Identity & access management ### 28.5.1 Users & memberships New `users` (email, display name, password hash (argon2id), TOTP fields, status) and `memberships` (`userId`, `tenantId`, `tenantRole`, `createdAt`). Login moves from "paste one API key" to email+password (+2FA), while **API keys remain first-class for programmatic access** — now owned by a tenant (`tenantId` + optional `allowedSessions` narrowing inside it) rather than by the deployment. ### 28.5.2 Two-factor authentication (TOTP) 2FA is included because the admin surface controls real WhatsApp sessions and message flows — shared API keys already outgrew "one strong secret is enough". - **Enrollment**: standard TOTP secret (shown once as text + otpauth:// QR), activated only after one valid code; 10 single-use **backup codes** (hashed at rest) for device loss. - **Enforcement modes**: per-user opt-in (default), tenant-enforced (tenant owner requires it for all memberships), platform-enforced (deployment-wide). - **Login flow**: email+password → short-lived `preAuthToken` → TOTP/backup-code challenge → full session token. `preAuthToken` can do nothing else and expires in 5 minutes. - **Reset**: tenant owner/platform admin can reset a member's 2FA (audit-logged); backup codes are single-use and regenerating them invalidates the previous set. - API keys are **not** behind 2FA (they are secrets, not logins) — same model as GitHub/AWS. ### 28.5.3 Role matrix (target) | Capability | Platform admin | Tenant owner | Tenant admin | Tenant operator | Tenant viewer | | ---------------------------------------- | ---------------- | ------------ | ------------ | --------------- | ------------- | | Provision/suspend tenants | ✓ | – | – | – | – | | Manage tenant members & roles | – | ✓ | ✓ | – | – | | Manage tenant API keys | – | ✓ | ✓ | – | – | | Create/delete sessions | – | ✓ | ✓ | – | – | | Send messages, manage webhooks/templates | – | ✓ | ✓ | ✓ | – | | View sessions, messages, logs | – | ✓ | ✓ | ✓ | ✓ | | Configure tenant branding | – | ✓ | ✓ | – | – | | Manage own 2FA | every named user | | | | | | Reset members' 2FA | ✓ | ✓ | – | – | – | ### 28.5.4 SSO / SCIM (phase 3 markers) OIDC login (Google/Microsoft/any IdP) and SCIM provisioning are deliberately deferred: they only make sense once users/memberships exist, and the membership model here is designed to accept them without schema change. ## 28.6 Per-tenant branding - **Linked-device identity**: the engine's browser display name (the `BAILEYS_BROWSER` tuple) resolves per session: `session.config.browserName` → `tenant.branding.deviceName` → global `BAILEYS_BROWSER_NAME` env → `'OpenWA'`. This supersedes the global-only env approach for white-label tenants while keeping a global fallback. - **Dashboard**: `tenant.branding` (display name, logo URL, optional accent color within the existing token system) applied at login and in the shell; global defaults when absent. - **Outbound identity**: webhook `User-Agent` and dashboard page titles take the tenant brand when present. ## 28.7 Data & storage isolation - **Session/engine data**: `SESSION_DATA_PATH//` (migration moves existing dirs under the default tenant). - **Media/object storage**: S3 prefix per tenant (or per-tenant bucket policy later); local storage mirrors the same layout. - **Backup/restore**: per-tenant export (sessions + config + keys + branding, message tables optionally excluded) so a tenant can be moved or archived independently. ## 28.8 Quotas & rate limiting New `tenant_quotas` (maxSessions, maxUsers, maxApiKeys, maxMessagesPerDay, maxWebhookEndpoints, maxPluginInstalls) with sensible unlimited defaults. The existing per-IP/per-key throttlers stay as coarse guards; per-tenant counters are checked at the same chokepoints (session create, key create, send path). ## 28.9 Plugins per tenant Installation stays platform-global (one code copy), **activation and config stay per session**, governed by an optional tenant policy: `tenant.pluginPolicy = { allow: [...], deny: [...] }` evaluated at install/enable time. Tenant secrets live only in that tenant's sessionConfig slice, as today. ## 28.10 Observability - **Audit log** gains `tenantId` (stamped from the same ALS actor point as `apiKeyId` today) and becomes tenant-filterable; platform admins see the deployment-wide stream. - **Metrics** (Prometheus) label session-scoped series with `tenantId` where cheap; dashboards can slice per tenant. - **Logs** keep the existing structured shape; the tenant id joins the per-request log context alongside `requestId`/actor. ## 28.11 API surface (additive, no breaking changes) - `POST/GET/PATCH/DELETE /api/platform/tenants` (platform admin), with suspend/resume. - `GET/POST/PATCH/DELETE /api/tenants/:tenantId/members` (tenant owner/admin). - `POST /api/auth/login` (email+password), `POST /api/auth/2fa/verify`, `POST /api/auth/2fa/enroll`, `POST /api/auth/2fa/activate`, `POST /api/auth/2fa/backup-codes`, `POST /api/auth/2fa/reset` (privileged). - `PATCH /api/sessions/:id` gains an optional `tenantId` (assign on create/move by platform admin). - Existing tenant-scoped routes resolve the tenant from the key/user; `X-Tenant-Id` header is accepted only from platform admins (tenant switching without a second key). - Public config endpoint exposes the active tenant's branding for the login page. ## 28.12 Dashboard UX - Login: email+password → optional TOTP challenge; tenant switcher in the sidebar for multi-tenant users; tenant admin pages (members, keys, branding, quotas); a 2FA section in the user menu (enroll, backup codes, reset for admins). - Every list/view is implicitly tenant-scoped; platform admins get an explicit tenant picker. ## 28.13 Migration & rollout 1. Create the **default tenant** and backfill: all existing sessions, API keys, plugin activations, and templates point at it; existing full-access API keys keep working untouched (they become keys of the default tenant). 2. Ship behind `MULTITENANCY_ENABLED=true` (default **off**): when off, the tenant layer is a no-op pass-through to the default tenant and behavior is byte-identical to today. 3. Dashboard gains user login as an _additional_ method; API-key login stays supported indefinitely. ## 28.14 Security model & test matrix - **Single chokepoint**: tenant context resolved in the guard; services never accept a tenant id from the client except the platform-admin override (28.11). - **No platform-admin read-path to tenant content by default** (support operations go through an explicit, audit-logged impersonation action). - **Required test matrix**: cross-tenant read on every tenant-owned route (sessions, messages, stats, webhooks, templates, plugins, audit), membership/role enforcement, 2FA enrollment and challenge, backup-code single-use, per-tenant quota denial, branding fallback order, migration idempotency (second boot is a no-op). ## 28.15 Phasing | Phase | Contents | Sizing note | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | | **P0 — Foundations** | Tenant entity + `tenantId` everywhere, default-tenant migration, guard chokepoint, tenant-scoped keys, cross-tenant test matrix, `MULTITENANCY_ENABLED` flag | The platform everything hangs off; largest single block | | **P1 — Users & 2FA** | users/memberships, email+password login, TOTP enroll/challenge/backup codes, tenant roles matrix, dashboard login + tenant switcher | Independent of P0's data model but layered on it | | **P2 — Branding, quotas, observability** | per-tenant branding (device name, dashboard, UA), tenant quotas + counters, audit `tenantId`, per-tenant backup/export | Mostly small, parallelizable pieces | | **P3 — Enterprise extras** | OIDC/SSO, SCIM provisioning, schema-per-tenant evaluation, audit export, impersonation support flow | Only after P0–P2 prove out | ## 28.16 Open questions 1. Do platform admins ever get a legitimate read path into tenant message content, and if so under what audit/impersonation ceremony? 2. Should tenant slug be immutable once sessions exist (webhook URLs may embed it later)? 3. Is per-message-type or per-recipient rate limiting part of tenant quotas, or left to the existing anti-abuse layer? 4. Does 2FA enforcement also cover API-key _management_ actions (create/revoke), not just login?