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.

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.