A multi-tenant app serves many customers (tenants) from the same codebase: a platform where each business gets its own storefront, data and branding. It is a powerful model for SaaS, and it adds a class of bugs that single-tenant apps never have: showing one tenant's data to another.
I worked on a Flutter SaaS app where business owners each get a branded storefront on their own subdomain, so these are lessons from that kind of design.
Rule zero: the server enforces isolation
The client can never be the security boundary. A tenant identifier sent from the app is a hint, not proof. The backend must derive the tenant from the authenticated session (or a verified subdomain) and apply it to every query: row-level security, tenant-scoped repositories, or separate schemas or databases. If a modified client could read another tenant's data, the fix belongs on the server.
What the client is responsible for is not leaking between tenants on the device and configuring itself correctly per tenant.
Tenancy models (backend, for context)
| Model | Isolation | Cost and ops |
|---|---|---|
Shared tables with tenant_id + RLS | Logical | Cheapest, easiest to scale |
| Schema per tenant | Stronger | More migrations to manage |
| Database per tenant | Strongest | Highest cost and complexity |
Your Flutter code looks similar for all three; the difference is how the API is addressed.
Resolving the tenant on the client
Typical sources, from most to least trustworthy:
- The authenticated session (the token carries the tenant).
- A tenant chosen at login (a business code or subdomain the user types).
- A white-label build flavor with a fixed tenant.
Model it explicitly instead of passing strings around:
class TenantContext {
const TenantContext({required this.id, required this.apiBaseUrl, required this.theme});
final String id;
final Uri apiBaseUrl;
final TenantTheme theme;
}
Per-tenant networking
If each tenant has its own API host, build the Dio client from the tenant context rather than a global constant:
Dio dioFor(TenantContext tenant) => createDio(baseUrl: tenant.apiBaseUrl.toString())
..options.headers['X-Tenant-Id'] = tenant.id; // convenience for routing/logging, never for authorization
When the tenant changes (login, switching business, logout), rebuild the dependencies that depend on it instead of mutating a shared singleton. With get_it, that means re-registering or using a scope; see dependency injection with get_it. In one design I used a main API service for the platform and a second one for the active tenant, re-registered at runtime on login, so nothing needed an app restart.
Cache isolation: the bug that bites
Anything persisted on the device must be keyed by tenant, or wiped when the tenant changes:
- Local databases: include
tenant_idin tables, or use one database file per tenant (tenant_<id>.db). - Key-value storage: namespace keys, for example
'$tenantId:cart'. - In-memory state: dispose BLoCs and repositories tied to the old tenant.
- Image and HTTP caches: separate or clear on switch.
- Tokens: store per tenant and clear on logout. See JWT refresh in Flutter.
A simple regression test: log into tenant A, load data, switch to tenant B, and assert that no A data is reachable through any repository.
Per-tenant theming and features
Load branding (colors, logo, name) from the tenant configuration and feed it into ThemeData. Gate features with tenant-level flags returned by the API, not with client-side if (tenantId == 'x') checks that spread through the codebase.
MaterialApp(
theme: ThemeData(colorSchemeSeed: tenant.theme.primaryColor),
/* ... */
)
Keep tenancy at the edges
Features should not know how tenants work. Put tenant resolution, base URLs and storage namespacing in the data and core layers so that an "orders" feature simply asks its repository for orders. This is the same inward-pointing dependency rule described in Clean Architecture in Flutter.
Key takeaways
- Isolation is enforced on the server; the client must not leak data between tenants locally.
- Model
TenantContextexplicitly and rebuild tenant-dependent dependencies when it changes. - Namespace or wipe every cache on tenant switch, and test it.
- Drive branding and features from tenant configuration.
Building a SaaS or white-label mobile product? See my projects or contact me.