Tenant Isolation

// tenant chosen by the client
const tenantId = req.header('X-Tenant-Id')
const ctx = { userId: session.userId, tenantId }
// every downstream query is now correctly scoped
// ...to a tenant the caller picked

const requested = req.header('X-Tenant-Id')
const memberships = await memberships.forUser(session.userId) // server-side truth

const tenantId = requested
  ? memberships.find((m) => m.tenantId === requested)?.tenantId
  : session.defaultTenantId

if (!tenantId) return res.status(403).json({ error: 'not_a_member' })
const ctx = { userId: session.userId, tenantId } // validated, then trusted

Both versions end with a correctly-scoped query. Only the second guarantees the value being scoped to is one the caller is entitled to — the predicate is only as trustworthy as the value in it. Note also that the first version is safe from SQL injection and completely broken for authorization; those are independent properties (The Trust Boundary).

1. 1
   Resolve at the edge

   Derive tenant from the principal; validate any selector against memberships

   fails by Reading a header or subdomain and using it directly

2. 2
   Carry in request context

   Per-request storage that every layer reads from

   fails by A module-level variable shared by concurrent requests (Backend Races)

3. 3
   Require it at the data boundary

   Repository methods take a tenant context; no table access outside them

   fails by A raw query written for a report, outside the repository

4. 4
   Inject the predicate

   Query layer or ORM scope adds tenant_id = ? to every tenant-scoped table

   fails by An escape hatch — unscoped, native SQL, bulk update — that skips the scope

5. 5
   Backstop in the database

   Row-level security evaluates the policy even if the app forgot

   fails by Connecting as an exempt role, or pooling that leaks the session variable

6. 6
   Namespace derived stores

   Tenant prefix on cache keys, object keys, index names, export filenames

   fails by A key built from an object id alone

7. 7
   Carry into async work

   Tenant in the job payload; workers build the same scoped context

   fails by A worker that looks the tenant up with an unscoped read

8. 8
   Prove it in CI

   Two-tenant fixture asserting every endpoint returns nothing for the other tenant

   fails by Testing endpoint by endpoint, so the new endpoint is untested

The first two steps are the ones with no acceptable alternative. The rest are defence in depth, and each has a documented way of being bypassed — which is why none of them alone is the answer (Defence in Depth).

1-- once, per tenant-scoped table
2ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
3ALTER TABLE invoices FORCE ROW LEVEL SECURITY;   -- also applies to the table owner
4 
5CREATE POLICY tenant_isolation ON invoices
6  USING (tenant_id = current_setting('app.tenant_id', true)::uuid);
7 
8-- per request, on the connection you are about to use
9SET LOCAL app.tenant_id = '…';   -- LOCAL: reset at transaction end
10 
11-- the trap, written out:
12--   SET  app.tenant_id  (no LOCAL) persists for the life of the
13--   connection, and the pool hands that connection to the next
14--   request. Correct policy, correct query, previous tenant.

Three details decide whether this works: FORCE (without it the table owner bypasses the policy entirely, which is often how the application connects), SET LOCAL inside a transaction so the value cannot outlive it, and the true second argument to current_setting so a missing setting returns NULL rather than raising — which makes the predicate false and denies, rather than erroring in a way something might catch and ignore.