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)

ModelIsolationCost and ops
Shared tables with tenant_id + RLSLogicalCheapest, easiest to scale
Schema per tenantStrongerMore migrations to manage
Database per tenantStrongestHighest 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:

  1. The authenticated session (the token carries the tenant).
  2. A tenant chosen at login (a business code or subdomain the user types).
  3. A white-label build flavor with a fixed tenant.

Model it explicitly instead of passing strings around:

dart
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:

dart
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_id in 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.

dart
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 TenantContext explicitly 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.