Skip to main content
Multi-tenancy allows a single deployment to serve multiple independent customers — called tenants — with complete data isolation between them. Each tenant operates as if they had their own dedicated environment, even though the underlying infrastructure is shared. In Lerian, multi-tenancy is available in SaaS (always active) and BYOC Multi-Tenant deployments.

​
How it works

Tenant isolation is enforced at the application layer through your authentication token.
  1. You authenticate via Access Manager and receive a JWT.
  2. That token includes a tenantId claim that identifies your tenant.
  3. On every API request, the platform resolves your tenant from the token automatically.
  4. All operations — creating organizations, querying ledgers, posting transactions — are scoped to your tenant.
You never pass a tenant identifier in headers or request bodies. The token handles it.
Multi-tenancy is transparent at the API level. Your integration code is the same whether you’re running single-tenant or multi-tenant — the only difference is that multi-tenant deployments require authentication on every request.

​
Tenant and organization relationship

A tenant is not the same as an organization. A single tenant can create and manage multiple organizations — for example, to represent subsidiaries, regional branches, or different business units. 
Tenant (resolved from JWT)
├── Organization A
│   ├── Ledger 1
│   └── Ledger 2
├── Organization B
│   └── Ledger 3
When you list organizations, you only see the ones that belong to your tenant. The same applies to every resource in the platform — ledgers, accounts, transactions, and balances are all scoped to your tenant automatically.

​
Data isolation

Tenant data is isolated at the database level. Each tenant operates on a separate database, meaning:
  • Data from different tenants is never stored together.
  • Queries from one tenant cannot reach another tenant’s data.
  • Even if two tenants create identical organization structures, their data remains completely separate.
This isolation is enforced by middleware that routes each request to the correct database based on the tenantId claim in your JWT. There is no way to bypass this through the API.
BYOC operators can choose between database-level or schema-level isolation depending on their infrastructure requirements.

​
What this means for you

​
If you are a SaaS customer

Nothing changes in how you use the API. Authenticate, get your token, and make requests. The platform handles isolation transparently. You don’t need to manage tenant identifiers or worry about data leaking between customers.

​
If you are a BYOC operator running multi-tenant

You configure which tenants exist and how their databases are provisioned. Your clients authenticate through Access Manager and receive scoped tokens. The platform routes each request to the correct tenant database automatically.

​
If you are running single-tenant (BYOC or local development)

Multi-tenancy is disabled by default. Your existing setup continues to work without changes. No JWT tenant claim is required, and authentication can be optional depending on your configuration.

​
Configuration (BYOC operators)

Multi-tenancy is disabled by default. To enable it, set MULTI_TENANT_ENABLED=true in the ledger (and CRM, if applicable) environment. Once enabled, the platform requires a running Tenant Manager service and authentication on every request.

​
Core settings

These variables apply to both the Ledger and CRM components:
VariableDescriptionDefault
MULTI_TENANT_ENABLEDEnable multi-tenant mode. When false, the platform runs in single-tenant mode.false
MULTI_TENANT_URLURL of the Tenant Manager service. Required when multi-tenant is enabled.—
MULTI_TENANT_SERVICE_API_KEYAPI key for authenticating with the Tenant Manager. Required when multi-tenant is enabled.—
MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SECHow often (seconds) the platform revalidates tenant configurations against the Tenant Manager.—
MULTI_TENANT_CACHE_TTL_SECHow long (seconds) tenant configuration is cached locally before re-fetching. Set to 0 to disable caching.120

​
Tenant Manager circuit breaker

Protects against Tenant Manager outages by failing fast when the service is unavailable:
VariableDescriptionDefault
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLDConsecutive failures before the circuit opens.5
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SECHow long (seconds) the circuit stays open before retrying.30

​
Redis cache

Multi-tenant mode uses Redis to cache tenant configurations across instances:
VariableDescriptionDefault
MULTI_TENANT_REDIS_HOSTRedis server hostname.—
MULTI_TENANT_REDIS_PORTRedis server port.6379
MULTI_TENANT_REDIS_PASSWORDRedis authentication password.—
MULTI_TENANT_REDIS_TLSEnable TLS for the Redis connection.false

​
CRM-specific settings

These variables are only available in the CRM component and control connection pool behavior for multi-tenant database connections:
VariableDescriptionDefault
MULTI_TENANT_TIMEOUTHTTP client timeout (seconds) for requests to the Tenant Manager.30
MULTI_TENANT_MAX_TENANT_POOLSMaximum number of concurrent database connection pools (one per active tenant).100
MULTI_TENANT_IDLE_TIMEOUT_SECHow long (seconds) before an idle tenant connection pool is evicted.300
For most deployments, the defaults work well. Tune CACHE_TTL_SEC and CONNECTIONS_CHECK_INTERVAL_SEC based on how frequently you add or modify tenants — lower values mean faster propagation of tenant changes, higher values reduce load on the Tenant Manager.
MULTI_TENANT_ENABLED=true requires PLUGIN_AUTH_ENABLED=true. Authentication must be active for tenant isolation to work — the platform resolves tenants from the JWT claim.

Deployment models

Understand the differences between SaaS, BYOC Single-Tenant, and BYOC Multi-Tenant.

Security

Learn about tenant isolation guarantees and the shared responsibility model.

Access Manager

Understand how authentication and JWT-based tenant resolution work.

Organizations

Learn how organizations are structured within a tenant.