Overview
A multi-tenant platform serves multiple organisations — tenants — from a single deployed system. Each tenant sees their own data, their own configuration, their own users, and in many cases their own branded experience, while sharing the underlying infrastructure, codebase, and operational overhead with every other tenant on the platform. Done correctly, this architecture is what makes SaaS businesses economically viable: the cost of infrastructure and operations scales far more slowly than the revenue from a growing tenant base.
Done incorrectly, multi-tenancy is a source of the most serious problems a software platform can have — tenant data leaking across boundaries, one tenant's activity degrading performance for others, configuration intended for one tenant affecting another, and the inability to scale individual tenants that grow significantly faster than the rest. These are not edge cases. They are the predictable consequences of multi-tenancy implemented as an afterthought rather than designed in from the beginning.
We build multi-tenant platforms with tenancy as a first-class architectural concern — not a feature added to a single-tenant system after the fact. Tenant isolation, data separation, per-tenant configuration, authentication and authorisation scoped to tenant boundaries, and the operational tooling to manage a growing tenant base are all designed in from the start. The result is a platform that can onboard new tenants efficiently, scale with the growth of individual tenants, and maintain strict separation between them throughout.
Tenancy Models
The first architectural decision in a multi-tenant platform is how tenant data is separated. The choice has implications for isolation strength, operational complexity, cost efficiency, and the ability to meet enterprise tenant requirements around data residency and compliance.
Shared Database, Shared Schema All tenants share a single database and a single schema, with a tenant identifier column on every table discriminating whose records are whose. This model is operationally simple — a single database to manage, backup, and scale — and maximally cost-efficient, since database resources are shared across all tenants.
The trade-off is isolation strength. Row-level security enforced at the application and database level prevents tenant data from leaking across boundaries, but the isolation relies on correct implementation throughout. A single missing tenant filter on a query exposes data across boundaries. Enterprise tenants with strict compliance requirements may not accept this model.
We implement shared-schema tenancy with row-level security enforced at both the application layer — tenant context propagated through every request and applied to every query — and the database layer, using PostgreSQL row-level security policies that enforce tenant isolation at the database level as a defence-in-depth measure independent of application logic.
Shared Database, Separate Schemas Each tenant gets their own schema within a shared database instance. Tenant data is separated at the schema level — queries against one tenant's schema cannot return another tenant's data without explicit cross-schema access. Operational overhead is moderate: a single database to manage, but schema-level migrations need to be applied across all tenant schemas when the data model changes.
This model provides stronger isolation than shared schema while retaining the operational simplicity of a single database. It is the right choice for platforms where the number of tenants is bounded and the compliance requirements of tenants warrant stronger isolation than row-level security alone.
Separate Databases Per Tenant Each tenant gets their own database instance — either on shared database infrastructure or on dedicated infrastructure for enterprise tenants. This provides the strongest isolation: a bug that exposes one tenant's data cannot affect another tenant's database. Data residency requirements can be met by locating each tenant's database in the appropriate region. Enterprise tenants can be given dedicated database infrastructure with the performance guarantees that entails.
The trade-off is operational complexity. Managing, monitoring, backing up, and migrating many separate database instances requires more sophisticated tooling than managing a single shared database. Schema migrations need to be applied across all tenant databases. Tenant provisioning requires database creation as part of the onboarding flow.
We design the tenancy model appropriate to the platform's requirements — and we design it so that it can evolve. Platforms that start with shared-schema tenancy and need to migrate specific tenants to dedicated databases as they grow should be able to do so without rebuilding the platform.
Tenant Isolation
Isolation is the core requirement of multi-tenant architecture. Every tenant must be confident that their data is not accessible to other tenants, that their configuration does not affect other tenants, and that their usage of the platform does not degrade the experience of other tenants.
Data Isolation Data isolation is enforced at multiple layers:
At the application layer, tenant context is established at the authentication boundary — every authenticated request carries a verified tenant identifier that is applied to every data access operation. Tenant context is not derived from user-supplied input after authentication; it is established from the verified identity token and propagated through the request pipeline. Middleware that enforces tenant scoping on every database query prevents the class of errors where a query is written without a tenant filter and inadvertently returns cross-tenant data.
At the database layer, row-level security policies enforce tenant isolation independently of application logic. Even if application code contains a bug that omits a tenant filter, the database rejects the query or returns an empty result rather than exposing cross-tenant data. This defence-in-depth approach means that data isolation does not depend on every query in the application being written correctly.
At the API layer, every endpoint validates that the resource being accessed belongs to the requesting tenant before returning data or accepting modifications. Resource identifiers that appear in API paths or request bodies are validated against tenant ownership, preventing tenant A from accessing tenant B's resources by guessing or enumerating identifiers.
Configuration Isolation Per-tenant configuration — feature flags, integration credentials, UI customisation, business rule parameters — is stored and applied in a way that makes cross-tenant contamination impossible. Configuration is loaded in the context of the authenticated tenant and never shared across tenant boundaries. Changes to one tenant's configuration take effect only for that tenant and do not affect the platform behaviour experienced by other tenants.
Performance Isolation One tenant generating unusually high query volume, processing large data imports, or consuming excessive API quota should not degrade the performance experienced by other tenants. We implement performance isolation through:
Per-tenant rate limiting at the API layer that bounds the request rate any single tenant can generate. Query timeout and resource limits at the database layer that prevent runaway queries from consuming database resources at the expense of other tenants. Background job queuing that prevents one tenant's batch processing from starving other tenants of processing capacity. Tenant-aware monitoring that surfaces per-tenant resource consumption and enables proactive intervention when a single tenant is generating disproportionate load.
Tenant Onboarding
The efficiency of tenant onboarding determines how quickly the platform can grow its tenant base and how much operational overhead each new tenant creates. Onboarding that requires manual intervention does not scale. Automated onboarding that provisions a new tenant's infrastructure, creates their initial users, configures their account, and sends them the access they need — triggered by a signup or a sales operation — scales with the business.
We build tenant onboarding flows that are fully automated:
Tenant provisioning. Database schema or database instance creation for the new tenant. Initial configuration seeding with the platform's default settings. Tenant record creation with the metadata the platform needs to route and identify the tenant.
User setup. Initial admin user creation for the tenant. Invitation flow that sends the tenant admin their access credentials or magic link. Role and permission seeding that gives the initial admin the access they need to configure the tenant account.
Integration initialisation. Webhook endpoint configuration for tenants that receive platform events. API key generation for tenants that access the platform programmatically. Third-party integration configuration where the platform integrates with external services on behalf of the tenant.
Billing initialisation. Subscription creation in the billing system, trial period configuration, and the metering infrastructure that tracks usage for consumption-based billing.
The onboarding flow is transactional — if any step fails, the partial onboarding is rolled back rather than leaving a half-provisioned tenant in an inconsistent state.
Per-Tenant Configuration and Customisation
Tenants have different requirements. An enterprise tenant may need SSO integration with their Active Directory. A tenant in a regulated industry may need specific data retention policies applied to their account. A tenant who has negotiated a custom plan may have access to features that are not available on standard tiers. A tenant deploying the platform to their own customers may need white-label branding applied to their instance.
We build per-tenant configuration systems that handle this breadth of customisation:
Feature flags per tenant. Each tenant's feature access is governed by a configuration layer that is independent of the codebase's feature flag system. Tenants on different plans have access to different features. Features can be enabled for specific tenants for beta testing, custom agreements, or troubleshooting without affecting other tenants.
Per-tenant authentication configuration. Enterprise tenants can configure their own OIDC or SAML identity provider, so their users authenticate through the organisation's existing SSO infrastructure rather than the platform's default authentication. The platform's authentication layer validates tokens from the tenant-configured identity provider and maps them to the platform's user model.
Branding and white-labelling. Tenants that deploy the platform to their own customers need their branding — logo, colours, domain, email sender identity — applied to the platform experience their customers see. White-label configuration is stored per-tenant and applied at the rendering layer, producing a fully branded experience for each tenant's end users without the platform brand appearing.
Per-tenant integrations. Tenants connect the platform to their own instances of external services — their Exact Online organisation, their Salesforce instance, their Slack workspace. Integration credentials are stored per-tenant in encrypted configuration, isolated from other tenants' credentials, and used only in the context of the tenant that owns them.
Data retention and compliance policies. Enterprise tenants with specific data retention requirements can have policies applied to their account that govern how long data is retained, when it is purged, and how it is handled for compliance purposes — applied at the tenant level rather than platform-wide.
Authentication and Authorisation in Multi-Tenant Platforms
Authentication in a multi-tenant platform needs to resolve not just who the user is but which tenant they belong to — and the authorisation model needs to enforce permissions at both the tenant level and within the tenant's own role hierarchy.
Tenant Resolution When a user authenticates, the platform needs to establish which tenant the session is in context of. For platforms with per-tenant domains or subdomains, tenant resolution is straightforward — the domain identifies the tenant. For platforms with a shared domain, tenant resolution comes from the user's identity — the tenant they are associated with is stored in the identity token or looked up from the user record.
We implement tenant resolution at the authentication middleware layer, establishing tenant context before any application code runs and propagating it through the request lifecycle. Requests that cannot be resolved to a tenant are rejected at the authentication boundary rather than reaching application code in an ambiguous state.
Within-Tenant Authorisation Each tenant has their own user hierarchy — administrators with full access, managers with scoped access, standard users with limited access, and potentially custom roles defined by the tenant themselves. The authorisation model enforces these within-tenant roles consistently across every operation, with the tenant boundary as the outermost scope — a user with admin access in tenant A has no access whatsoever to tenant B.
Auth0 for Multi-Tenant Identity Auth0's organisations feature maps directly to the multi-tenant model — each tenant is an Auth0 organisation with its own user directory, its own SSO configuration, and its own branding applied to the authentication UI. Platform users are members of their tenant's organisation, and the organisation identifier is embedded in their identity token, providing verified tenant context on every authenticated request.
Privy for Web3 Multi-Tenant Platforms For Web3 platforms where users authenticate with wallet addresses or social identity bridged to on-chain identity, Privy's multi-tenant capabilities handle wallet-based identity within tenant boundaries — each tenant's users have wallets scoped to the tenant context, and on-chain operations initiated by the platform are scoped to the correct tenant's configuration.
Billing and Subscription Management
Multi-tenant platforms are typically subscription businesses. The billing infrastructure needs to handle plan tiers, usage-based components, trial periods, upgrades and downgrades, failed payment handling, and the reporting that gives the business visibility into its revenue.
Stripe Integration We integrate Stripe as the billing infrastructure for multi-tenant platforms — handling subscription creation, plan management, usage metering for consumption-based billing, invoice generation, payment method management, and the webhook processing that keeps the platform's subscription state in sync with Stripe's billing state.
Per-tenant subscription state is maintained in the platform database and kept in sync with Stripe through webhook processing. The platform's feature access and rate limit configuration for each tenant is derived from their current subscription state — a tenant whose payment fails automatically has their access restricted without manual intervention, and a tenant who upgrades their plan immediately gets access to the features their new plan includes.
Usage Metering For platforms with consumption-based billing components — API calls, data storage, active users, processed records — we build usage metering infrastructure that counts consumption per tenant, aggregates it for billing periods, and reports it to Stripe's metered billing APIs for inclusion in invoices.
Usage metering is designed to be accurate and auditable — tenants can see their own consumption in their account dashboard, and the platform operator can see consumption across the full tenant base for revenue reporting and capacity planning.
Platform Administration
Managing a multi-tenant platform requires operational tooling that gives the platform operator visibility into and control over the full tenant base:
Tenant management dashboard. A comprehensive view of all tenants — their subscription status, their usage metrics, their configuration, their active users, and the ability to impersonate a tenant session for support purposes with full audit logging of impersonation activity.
Usage and revenue reporting. Aggregated and per-tenant views of platform usage, active tenant counts, monthly recurring revenue, churn, and the metrics that drive the business decisions of a SaaS operation.
Tenant health monitoring. Per-tenant error rates, API latency, queue depths, and the signals that indicate a tenant is experiencing problems — surfaced to the platform operator before the tenant raises a support request.
Configuration management. The ability to modify tenant configuration, apply feature flags, adjust rate limits, and manage subscription state from a central administrative interface — with audit logging of every administrative action.
Scalability Architecture
A multi-tenant platform that works at ten tenants needs to still work — and work well — at ten thousand. The architectural decisions that determine scalability are made at the beginning:
Horizontal scaling. Application services are stateless, running behind load balancers with session state held in Redis rather than in process memory. Adding application instances scales API capacity without architectural changes.
Database scaling. Read replicas separate analytical and reporting queries from the write path. Connection pooling manages database connections efficiently as the number of application instances grows. For platforms with separate-database tenancy, database infrastructure scales independently per tenant.
Background processing. Job queues separate background processing from the API request path, allowing background processing capacity to scale independently. Per-tenant queue partitioning ensures that one tenant's background job backlog does not delay processing for other tenants.
Caching. Per-tenant caching at appropriate layers — configuration cache, session cache, frequently-accessed data cache — reduces database load and improves response times at scale. Cache invalidation is scoped to tenant boundaries so that cache operations for one tenant do not affect the cache state of another.
Technologies Used
- React / Next.js — frontend for multi-tenant SaaS platforms, tenant dashboards, admin interfaces
- TypeScript — type-safe frontend and backend code throughout
- Rust / Axum — high-performance multi-tenant API backends, usage metering services, real-time data delivery
- C# / ASP.NET Core — enterprise multi-tenant backend services, complex business logic, enterprise integrations
- PostgreSQL — primary multi-tenant data store with row-level security, per-tenant schemas
- MySQL — alternative relational store for platforms with existing MySQL infrastructure
- Redis — session storage, per-tenant caching, job queues, rate limit state
- Auth0 (Organisations) — multi-tenant identity management, per-tenant SSO, social login
- OAuth2 / OIDC — enterprise tenant identity provider integration
- Privy — Web3 multi-tenant identity and embedded wallet infrastructure
- Stripe — subscription management, usage metering, billing infrastructure
- Systemd / Linux — reliable service management for platform backend services
- AWS EC2 / S3 / SQS — cloud infrastructure for elastic scaling of platform components
When to Build Multi-Tenant From the Start
The cost of retrofitting multi-tenancy onto a single-tenant system is high — often approaching the cost of a rebuild. Data models need to be restructured. Authentication needs to be rearchitected. Every query needs tenant filtering added. Every API endpoint needs tenant validation added. Every configuration system needs tenant scoping added.
Building multi-tenant from the start costs more than building single-tenant — the additional architectural complexity is real. But for any platform that will eventually serve multiple organisations, the investment is lower than the cost of the retrofit, and the risk of data isolation failures during the retrofit is avoided entirely.
If the platform will serve more than one organisation — even if it starts with just a handful of tenants — build it multi-tenant from the beginning.
Build Your Multi-Tenant Platform
Whether you are building a new SaaS platform from scratch, adding multi-tenancy to an existing product, or rebuilding a single-tenant system to serve multiple organisations — we have the architecture experience to design and deliver it correctly.