Skip to main content
Technology & EngineeringSystem Design35 lines

Multi-tenant SaaS Isolation

Design tenant boundaries across APIs, databases, queues, caches and exports, then test cross-tenant denial.

Quick Summary7 lines
Use this skill when a service hosts multiple organizations and their data must remain separated. Inventory every tenant-owned resource and every operation that can access it, including administrative jobs, downloads and support tools. A tenant ID is not an authorization decision.

## Key Points

- [PostgreSQL row security](https://www.postgresql.org/docs/current/ddl-rowsecurity.html)
skilldb get system-design-skills/multi-tenant-saas-isolationFull skill: 35 lines
Paste into your CLAUDE.md or agent config

Multi-tenant SaaS Isolation

Use this skill when a service hosts multiple organizations and their data must remain separated. Inventory every tenant-owned resource and every operation that can access it, including administrative jobs, downloads and support tools. A tenant ID is not an authorization decision.

Choose and enforce boundaries

Compare shared tables, separate schemas and separate databases against recovery, residency, scaling and operational requirements. Document where isolation is logical and where infrastructure is shared. Do not claim physical separation for a shared database.

Derive tenant membership from authenticated server context and a server-side membership check. Treat route parameters, headers, object IDs and form fields as untrusted selectors. Scope reads and mutations using both the resource ID and authorized tenant. Validate ownership again when linking related objects.

For shared relational tables, make tenant ownership explicit in keys, constraints and indexes. Consider row-level security as defense in depth. PostgreSQL table owners, superusers and roles with BYPASSRLS can bypass normal policies; inspect the actual role and policy behavior. Distinguish visibility conditions from checks on inserted or updated rows.

Extend isolation beyond SQL

Include tenant identity in cache keys, object-storage authorization, search filters, job payloads and exported file access. Sign a download only after checking current access. A background worker must reconstruct authorized tenant scope and reject missing or inconsistent metadata.

Use transaction-scoped database context with connection pools so state cannot remain attached to a reused connection. Apply per-tenant quotas where one tenant could exhaust shared resources. Keep cross-tenant administrative operations explicit, narrowly authorized and auditable.

Prove denial

Create fixtures with two tenants, a multi-tenant member, a removed member and an unauthenticated caller. Test reads, updates, inserts, deletes, joins, nested routes, bulk operations, search and asynchronous exports. Attempt foreign IDs and mixed-tenant batches. Test with the actual application role, not a privileged migration account.

Exercise connection reuse, stale caches, delayed jobs and membership removal. Error responses should not expose another tenant's names or record contents. Verify that a migration preserves ownership and constraints before switching traffic.

Deliver a boundary map, role inventory, executable negative tests and migration rollback plan. State any bypass paths retained for operations and the controls around them. A successful same-tenant request proves functionality; denial cases provide the evidence for isolation.

References

Install this skill directly: skilldb add system-design-skills

Get CLI access →