Multi-Tenant SaaS: Decisions to Make
Before Your First Customer
Five decisions shape a multi-tenant SaaS product from its first customer: the tenant boundary, roles, plan limits, per-tenant integrations and one source of truth. Here is what to settle early and what can wait.
A multi-tenant SaaS architecture lets many customer organisations, or tenants, share one product while each sees only its own data, users and settings. A handful of decisions in that architecture are hard to reverse once customers depend on them, so they belong before the first customer signs in.
The short answer: before your first customer, decide how tenants are isolated, how users and roles work inside a tenant, how the product enforces plans and limits, how each tenant's integrations run within outside API limits, and which system holds the truth for shared data. Dedicated infrastructure, enterprise sign-on and advanced pricing can wait for the customers who ask for them.
What is a multi-tenant SaaS architecture?
A tenant is usually a customer organisation with many users. Microsoft's architecture guidance treats the choice of tenancy model as a commercial decision as much as a technical one, and describes isolation as a spectrum: you can share some layers and separate others (Microsoft Learn). Here is how multi-tenant vs single-tenant models compare, with two partly shared models in between.
| What tenants share | Fits when | Watch for |
|---|---|---|
| Fully multi-tenant | ||
| Application, database and infrastructure | You expect many customers and cost per tenant matters. |
|
| Database per tenant | ||
| The application tier; database compute may also be shared | Database load or data separation is the main concern. |
|
| Mixed | ||
| Most tenants share; some get dedicated deployments | A few customers need stronger isolation or performance. |
|
| Single-tenant per customer | ||
| No application or data resources; deployment tooling can still be shared | You expect few customers, or isolation requirements are strict. |
|
Fully multi-tenant
What tenants share
Application, database and infrastructureFits when
You expect many customers and cost per tenant matters.Watch for
- Data leaking between tenants
- One tenant's load slowing others
- Every change reaching everyone at once
Database per tenant
What tenants share
The application tier; database compute may also be sharedFits when
Database load or data separation is the main concern.Watch for
- Deploying and migrating many databases automatically
Mixed
What tenants share
Most tenants share; some get dedicated deploymentsFits when
A few customers need stronger isolation or performance.Watch for
- Code that supports both
- Moving a tenant between deployments
Single-tenant per customer
What tenants share
No application or data resources; deployment tooling can still be sharedFits when
You expect few customers, or isolation requirements are strict.Watch for
- Cost that grows with every tenant
- Updating every deployment
The same guidance points to shared infrastructure when you expect many customers, and to dedicated resources when you expect few or when their isolation requirements are high. The marketplace seller platform case study is the shared kind: many sellers on one platform, which now processes more than 500,000 orders a day across all of them.
Tenant isolation: what must never leak?
AWS describes any breach of the tenant boundary as a potentially unrecoverable event for a SaaS business (AWS). The boundary has to hold everywhere data travels, which is more places than the main database.
The tenant travels with every request. Set at sign-in, checked wherever data is read or changed, carried everywhere else.
Set
- Sign-in The identity provider adds the tenant to the signed-in session.
Check
- API and screens The tenant comes from the session. Each record is checked against the tenant and the user's role.
- Database Every tenant-owned row has a tenant ID. Row-level security can act as a second line.
Carry
- Queues and jobs Every message and background job carries the tenant ID it works for.
- Caches, search, files Cache keys, search indexes and file paths include the tenant.
- Logs and metrics Every entry is tagged with the tenant, so support and monitoring can see one tenant at a time.
Take the tenant from the signed-in session, and check it on every read and write.
OWASP ranks Broken Object Level Authorization first among API security risks: an API returns or changes a record because the caller supplied its ID, without checking that the caller may use it (OWASP). In a multi-tenant product, every such check asks at least two things: does this record belong to the caller's tenant, and does the caller's role allow this action?
A database rule can back up the application. PostgreSQL row-level security restricts which rows a role can read or change, and with security enabled and no policy defined, it denies normal row reads and changes for roles subject to its policies (PostgreSQL).
Practical note: If you use PostgreSQL row-level security as a safety net, check which role your application connects as. Table owners bypass the policies unless the table is set to force row-level security, and superusers and roles with the BYPASSRLS attribute always bypass them.
Test isolation the way an attacker would: create two tenants with similar data, then call every endpoint as a user of one with the other's record IDs. Microsoft's guidance asks you to test that one tenant's data cannot leak to another, whatever model you choose.
How should accounts, roles and permissions work?
Separate who someone is from what they may do in a given tenant. Microsoft advises against building your own identity provider and points out that one person may belong to several tenants, with admin rights in one and limited access in another (Microsoft Learn). Model memberships from the start: a user, a tenant and a role, so a consultant or an agency can switch between client accounts without a second login.
Name the roles after the work people do. The marketplace platform serves store owners, operations, support and finance; the AI agent platform MVP was built for team admins, builders and operators. Decide which actions need approval, keep an audit trail of who changed what, and define how your own support staff can view a tenant's account: with permission, for a limited time and logged.
Roles decide what each person sees on each screen, so they are as much a part of SaaS design as onboarding and plan upgrades.
Plans and limits: what belongs in your SaaS billing integration?
A plan is a promise about features and limits, and the product has to keep it. Microsoft's guidance on pricing models warns that a flat-rate plan without per-tenant usage limits can become unprofitable, recommends telling customers about limits before they reach them, and advises testing billing like any other part of the system (Microsoft Learn).
In the agent platform, subscriptions come with 5, 10 or 20 agents and a token allowance, and enterprise customers get custom limits. The platform uses those limits to help control usage and spending, and billing and limits were part of the delivered MVP.
Plans and limits, from billing to the moment of use. Billing records what a tenant has paid for. The product enforces it.
- The billing provider holds the subscription It sends an event whenever the tenant's plan changes.
- The product updates the tenant's plan Verify the event, skip duplicates, store features and limits.
- Each action is checked against the plan Allowed, or stopped with the limit explained.
- Usage is recorded per tenant Shown to the tenant's admins against their limits.
Example
5 · 10 · 20 agents per subscription plan
- A token allowance
- Custom limits for enterprise customers
Used by the platform to help control usage and spending. Included in the delivered MVP.
Stripe's Entitlements feature maps your features to Stripe products and sends an event whenever a customer's entitlements change; Stripe recommends keeping a copy of them in your own system (Stripe). Billing events need careful handling: Stripe notes that an endpoint may receive the same event more than once and that events may arrive out of order. It recommends verifying signatures, logging the event IDs you have processed and handling events asynchronously. When order matters, retrieve the current subscription or entitlement state instead of assuming the last event received is the newest (Stripe). In the marketplace platform, Stripe was integrated for the project's payments, refunds, payouts and platform subscription billing.
How do you run integrations per tenant within API limits?
When tenants connect their own accounts to outside services, each connection has to run at the pace that service's API allows. In the marketplace platform, orders, listings, messages and returns come in from five marketplaces, each through a queue that respects that marketplace's API limits. Channel-specific rules stay inside the connectors; the platform holds the truth.
Microsoft's rate limiting pattern describes the same approach: put work on a durable queue and let processors take it at a rate the outside service accepts, with retries coordinated with that limit (Microsoft Learn). Add tenant fairness on top, so one tenant's backlog cannot hold up everyone else's updates, and show each tenant the status of its own connections.
How do you keep one source of truth under load?
When the same data exists in several systems, decide which one is authoritative and treat the rest as copies.

500,000+ orders processed a day
The marketplace platform keeps one stock ledger per SKU; the quantity shown on each marketplace is a copy the platform updates, which can lag behind the ledger. Its rules:
- Reserve first. An incoming order is recorded once, even if the marketplace sends it twice, and reserves stock in the same atomic step.
- Push zero first. Each marketplace receives only the latest quantity, through its own queue, and an update to zero goes ahead of routine changes.
- Buffer slow channels. Channels that update slowly can show slightly less than the ledger's available stock.
- Handle the race. An order for stock that is already gone goes to a conflict queue: another warehouse if there is one, a backorder if the seller allows it, otherwise a cancellation.
- Reconcile on a schedule. A job compares listings with the ledger and corrects drift.
The platform runs on Java, Spring Boot, PostgreSQL, Kafka and Redis, in Docker and Kubernetes. It reached production after four months of development, built in this order: the ledger and first connectors, all five marketplaces, the inbox and returns, then Stripe integration and the multi-tenant launch.
What do you need to support tenants once they are live?
Tag every log line, metric and trace with the tenant. Microsoft's guidance on the noisy neighbour problem recommends monitoring both overall usage and each tenant's usage, alerting on spikes, and applying quotas or throttling so one tenant cannot overwhelm the shared system, while being open with customers about those limits (Microsoft Learn). Give your support team a per-tenant view of plan, usage, connection status and recent failures, so a question from a customer starts with facts.
What can wait until you have customers?
| Area | Decide before the first customer | Can wait for customers who ask |
|---|---|---|
| Isolation | Tenant ID on tenant-owned records and on every request, message and log; checks on every object | Separate databases or deployments for specific tenants |
| Identity | Memberships and roles inside a tenant, on a managed identity provider | Single sign-on with each customer's own identity provider; automated user provisioning |
| Billing | Plans, limits enforced in the product, safe handling of billing events | Usage-based pricing, discounts and custom contracts |
| Integrations | Queues that respect each outside API's limits | More channels and custom connectors for individual customers |
| Operations | Per-tenant logs, usage and alerts | Detailed usage reports and dashboards for customers |
Isolation
Decide before the first customer
Tenant ID on tenant-owned records and on every request, message and log; checks on every object
Can wait for customers who ask
Separate databases or deployments for specific tenants
Identity
Decide before the first customer
Memberships and roles inside a tenant, on a managed identity provider
Can wait for customers who ask
Single sign-on with each customer's own identity provider; automated user provisioning
Billing
Decide before the first customer
Plans, limits enforced in the product, safe handling of billing events
Can wait for customers who ask
Usage-based pricing, discounts and custom contracts
Integrations
Decide before the first customer
Queues that respect each outside API's limits
Can wait for customers who ask
More channels and custom connectors for individual customers
Operations
Decide before the first customer
Per-tenant logs, usage and alerts
Can wait for customers who ask
Detailed usage reports and dashboards for customers
If you are still deciding what the first release should contain, the decisions to make before the first customer are the multi-tenant part of MVP development. The rest can wait for later SaaS development work, when customers ask for it.
Sources
- Microsoft Azure Architecture Center — Tenancy models for a multitenant solution
- Microsoft Azure Architecture Center — Multitenancy and Azure SQL Database
- AWS Well-Architected SaaS Lens — Tenant isolation
- OWASP API Security Top 10 (2023) — API1 Broken Object Level Authorization
- PostgreSQL documentation — Row Security Policies
- Microsoft Azure Architecture Center — Architectural considerations for identity in a multitenant solution
- Microsoft Azure Architecture Center — Pricing models for a multitenant solution
- Stripe Docs — Entitlements
- Stripe Docs — Receive Stripe events in your webhook endpoint
- Microsoft Azure Architecture Center — Rate Limiting pattern
- Microsoft Azure Architecture Center — Noisy Neighbor antipattern
Frequently asked questions
Only when your customers' isolation requirements or a database bottleneck call for it. A database per tenant separates data, but databases can still share compute, as in Azure SQL elastic pools. Performance isolation also depends on resource limits and dedicated capacity. Every schema change then runs across many databases, so it needs automation from the start. The mixed model in the table above is a middle path: one shared database, with individual tenants moved to dedicated resources when there is a reason.
Yes, but the change reaches every query, background job, cache and integration. Adding a tenant ID to tenant-owned records from the first day, even with one customer, reduces later migration work. It still needs permission checks and isolation tests across those paths.
On every change. OWASP recommends tests that check authorisation and stop a deployment when they fail. Cover background jobs, exports and search as well as the API, because those paths are easy to forget.
Planning a SaaS product?
Tell us who your tenants are, what they pay for and which outside systems the product depends on. We can help you settle the tenant boundary, roles, plans and limits before your first customer signs in.
