> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Multi-tenancy
> How Lerian Cloud and supported BYOC products isolate tenants, and how to choose dedicated or shared storage.
Multi-tenancy lets one deployment serve independent customer contexts — **tenants** — while keeping each request and its data within the authenticated tenant's scope.
Lerian Cloud is operated as a multi-tenant environment. In BYOC, multi-tenancy is available only for products and entitlements that support it; a BYOC Single-Tenant deployment is a separate configuration.
## Product support
***
Tenant scoping and configuration are product-specific. The product documentation currently describes multi-tenant operation for:
| Product | Scope documented in its product docs |
| :----------- | :------------------------------------------------------------ |
| **Midaz** | Organizations, ledgers, accounts, transactions, and balances. |
| **Tracer** | Rules, limits, validation decisions, and audit events. |
| **Reporter** | Configured report data sources and generated reports. |
| **Matcher** | Reconciliation resources. |
Use the authentication and configuration guide for the product you are deploying. Do not assume an environment variable, JWT claim, or API behavior documented for one product applies to another.
## Authentication and request scoping
***
Each product validates the caller's identity and derives its tenant context according to that product's authentication contract. In a multi-tenant deployment, use the supported Access Manager flow and include the Bearer token required by the product.
The platform does not define one universal `tenantId` claim or one universal tenant header for every product. A product integration must follow that product's documented claim and routing behavior; do not add a tenant identifier to a request unless that product explicitly requires it.
Multi-tenancy is an operational capability, not a promise that every Lerian product has the same authentication middleware or configuration surface.
## Storage isolation
***
Tenant Manager service registrations use the values `dedicated` and `shared`. This documentation uses the corresponding deployment concepts below:
* **`DATABASE` (`dedicated`)** — a tenant receives a dedicated PostgreSQL database.
* **`SCHEMA` (`shared`)** — tenants share a PostgreSQL database and each receives a dedicated schema.
The `DATABASE` / `SCHEMA` distinction is specific to PostgreSQL. Other datastores use their own mode-specific routing and provisioning rules; do not infer PostgreSQL schema behavior for MongoDB or RabbitMQ.
| Dimension | `DATABASE` (`dedicated`) | `SCHEMA` (`shared`) |
| :--------------------------- | :-------------------------------------------------------------- | :------------------------------------------------------------------ |
| **PostgreSQL isolation** | Separate database per tenant. | Separate schema in a shared database. |
| **Operational blast radius** | A database-level incident is limited to that tenant's database. | A database-level incident can affect tenants sharing the instance. |
| **Cost and density** | Higher isolation, more infrastructure per tenant. | Higher density, less infrastructure per tenant. |
| **Restore design** | Plan and test restores for the dedicated database. | Plan and test restores against the shared database and its schemas. |
Choose the mode per service according to the service's supported configuration, regulatory obligations, expected workload, and recovery requirements.
## Moving a tenant between modes
***
Moving a tenant from shared to dedicated storage is an operator-planned migration, not a generic automatic platform workflow. Validate the target product's migration path, data-consistency requirements, maintenance window, backup/restore plan, and rollback procedure before changing a tenant's service registration.
The tenant identity can remain stable, but do not assume every product can move data between modes without an implementation-specific migration.
## Operating each deployment model
***
### Lerian Cloud
Lerian operates the multi-tenant infrastructure. Follow the product's API and authentication documentation; your token and the product's routing contract determine the request scope.
### BYOC Multi-Tenant
The operator configures the supported products, tenant services, storage mode, backing resources, and authentication. Treat each product's configuration reference as authoritative.
### BYOC Single-Tenant or local development
Multi-tenancy is not automatically enabled. Authentication requirements depend on the product and environment; for Midaz, production and multi-tenant deployments require authentication, while a permitted non-production single-tenant deployment can disable it.
## Configuration
***
There is no cross-product environment-variable contract for multi-tenancy. Do not copy a generic list of `MULTI_TENANT_*` variables between Midaz, Tracer, Reporter, and Matcher.
For Midaz, multi-tenant operation requires its product-specific configuration, including `MULTI_TENANT_ENABLED`, `PLUGIN_AUTH_ENABLED`, and `APPLICATION_NAME`. Confirm the current values, defaults, and dependencies in the Midaz configuration reference before deploying. Other products have their own configuration contracts.
## Related pages
***
How tenant services and their backing resources are provisioned.
How to choose dedicated or shared PostgreSQL isolation.
Compare Lerian Cloud, BYOC Single-Tenant, and supported BYOC Multi-Tenant configurations.
Understand the supported authentication flows for the products you deploy.