Multi-tenant isolation: do's and don'ts
Updated 2026-05-07
Multi-tenant isolation is the single highest-stakes correctness property in B2B SaaS. The teams that build it as defense-in-depth across application, audit, database, and key layers don't have cross-tenant incidents; the teams that build it as a single application-layer filter eventually do.
For the architectural treatment, see the multi-tenant architecture guide and the B2B SaaS identity guide.
Do
Include tenant_id in every claim, every query, every audit event
Defense in depth, even when application logic forgets to filter, the database layer (RLS), the audit layer, and the auth layer all reinforce the boundary.
PostgreSQL Row-Level Security documentation; multi-tenant SaaS architecture patterns. Production SaaS that treats tenant_id as an afterthought routinely produces cross-tenant data leaks; SaaS that bakes it into every layer rarely does.
Test cross-tenant access explicitly in CI
Tenant isolation is a property the test suite can verify. Test cases that attempt to access tenant A's data while authenticated as tenant B should fail with 404 or 403.
Multi-tenant SaaS that ships isolation tests as part of CI catches regressions immediately. SaaS without these tests has discovered isolation bugs months after introduction.
Audit tenant_id changes specifically, they should be rare
Tenant_id mutation is almost never a legitimate operation. Treating any tenant_id change as a privileged operation requiring admin signoff catches malicious or accidental tenant moves.
Standard B2B multi-tenant pattern. Several documented incidents where users accidentally moved between tenants because tenant_id was mutated as part of a different operation; the audit layer would have caught it.
Scope the JWT token's claims to a single tenant context
A user with multi-tenant memberships should hold a token scoped to one tenant at a time. Switching tenants should re-authenticate or require explicit consent, not silently broaden the token's authority.
Auth0 Organizations, Frontegg, WorkOS Organizations all ship per-Org session tokens. The pattern of multi-tenant tokens with claim-based switching is workable but routinely produces audit ambiguity.
Don't
Don't trust the tenant_id in user-supplied input
If the tenant_id comes from a request parameter or header, the user can manipulate it to access another tenant. The tenant context must come from the authenticated session.
Documented IDOR (Insecure Direct Object Reference) vulnerabilities at multi-tenant SaaS specifically traced to user-supplied tenant context. The fix is structural: never read tenant_id from the request.
Don't share encryption keys across tenants
Per-tenant encryption keys ensure that compromise of one tenant's data doesn't compromise another's. Shared keys make multi-tenant data effectively single-tenant from a key-compromise perspective.
AWS KMS multi-tenant patterns and similar guidance from GCP and Azure. Production SaaS that handle regulated data per-tenant invariably move to per-tenant keys.
Don't use the same database user for multiple tenants without RLS
Without Row-Level Security, the database has no enforcement of tenant boundaries beyond what application queries explicitly filter. A query that forgets the tenant_id WHERE clause can return any tenant's data.
PostgreSQL RLS is the canonical defense. Production SaaS that rely solely on application-layer filtering have produced cross-tenant data leaks; SaaS using RLS as defense in depth catches the bugs the application missed.
Don't expose tenant identifiers in URLs that leak across tenants
Sequential or guessable tenant_ids enable enumeration. Use UUIDs or other non-sequential identifiers for tenant URLs.
OWASP IDOR prevention and standard multi-tenant SaaS patterns. Sequential tenant IDs combined with URL exposure have produced documented enumeration attacks.