Multi-tenant SaaS Isolation
Design tenant boundaries across APIs, databases, queues, caches and exports, then test cross-tenant denial.
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 linesMulti-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
Related Skills
Rate Limiting Design
Rate limiting and throttling strategies for protecting distributed systems at scale
API Gateway Design
API gateway and Backend-for-Frontend (BFF) patterns for managing client-service communication
Double-entry Billing Ledgers
Model immutable balanced postings, idempotent financial events, reversals and reconciliation for billing systems.
Circuit Breaker
Circuit breaker and resilience patterns for building fault-tolerant distributed systems
Database Scaling
Database scaling patterns including sharding, replication, and read replicas for high-throughput systems
Distributed Caching
Distributed caching strategies for reducing latency and database load in large-scale systems