Multi-Tenancy

Apache Fineract is built to run multiple fully independent financial institutions on a single platform - each with its own isolated data, its own users, its own products, its own configuration, and its own transaction history. These independent environments are called tenants.

From the outside, every tenant looks and behaves like its own standalone Fineract instance. A branch officer at one institution has no visibility into another institution's data. Products configured for one tenant do not appear in another. Reporting, accounting, and compliance data are completely separate. The only thing tenants share is the underlying infrastructure.

This architecture has significant implications for how Finecko can be deployed and who it is suitable for.

Who Uses Multi-Tenancy

SaaS Providers and Core Banking Hosts

If you offer core banking as a service to multiple financial institutions - community banks, MFIs, credit unions, SACCOs, or fintech companies - multi-tenancy lets you operate all of them on a single managed platform instead of running a separate installation for each customer.

Each customer gets their own isolated environment. Onboarding a new client means provisioning a new tenant, not deploying new servers, managing new infrastructure, or maintaining a separate codebase. Upgrades, patches, and maintenance happen once at the platform level and propagate to all tenants automatically.

Holding Groups and Financial Conglomerates

A holding group that operates multiple regulated entities - a commercial bank, a microfinance subsidiary, and a rural savings cooperative, for example - may need to keep those entities completely separated for regulatory, audit, and governance reasons, while still running them on shared infrastructure.

Multi-tenancy provides that separation at the data level. Each regulated entity is its own tenant. Consolidation reporting can pull data across tenants at the holding group level without the entities having any access to each other's records.

Pilot Programs and Sandbox Environments

Running a pilot program, testing a new product design, or validating a configuration change before it reaches production are all natural use cases for a dedicated tenant. A pilot tenant has a real Fineract environment - full schema, real APIs, real reporting - but is completely isolated from the production environment running alongside it.

Teams can experiment freely, reset configuration, and iterate without any risk to live data. When the pilot is ready to graduate, its configuration can be replicated to the production tenant.

Regional or Branch-Level Separation

Larger institutions with significant regional divisions sometimes need separate books and separate user management per region, even within a single legal entity. A multi-tenant deployment lets each region operate as its own environment while remaining on the same platform and subject to the same central product catalogue and reporting infrastructure.

Development, Staging, and Production Environments

Running development, staging (UAT), and production as separate tenants on the same platform is a clean way to manage the software lifecycle. Developers work against the development tenant, QA validates against staging, and production runs alongside both without interference. All three share the same Fineract version and benefit from the same upgrade cycle.

What is Isolated Per Tenant

Every tenant has its own:

• Database - all loan data, client records, savings accounts, transactions, accounting entries, and configuration are stored in a dedicated database that no other tenant can access
• Users - the user base is entirely per-tenant; a super-admin in one tenant has no authority or visibility in any other tenant
• Products - loan products, savings products, and deposit products are configured independently per tenant
• Charges and fees - fee structures, penalty configurations, and charge types are set per tenant
• Accounting - chart of accounts, journal entries, and financial statements are fully separate
• Business rules - working days, holidays, COB (Close of Business) schedules, and batch job configuration are per tenant
• External event subscriptions - which business events are enabled and where they are delivered is configured per tenant
• Reports - report definitions and output are scoped per tenant

What is Shared Across Tenants

Running multiple tenants on one platform means sharing the infrastructure that hosts them. What is shared:

• The Fineract application servers (JVM processes, thread pools)
• The message broker connections (Kafka or ActiveMQ)
• The database server hardware (though each tenant has its own database on that server)

Sharing compute and infrastructure is what makes the economics of multi-tenancy attractive. The marginal cost of adding a new tenant is the cost of a new database, not a new server deployment.

For institutions with strict regulatory requirements around infrastructure separation, dedicated application server deployments can be configured per tenant while still using the Hub to manage provisioning centrally.

Independent Configuration Without Interference

One of the most operationally significant properties of Fineract's multi-tenancy is that configuration changes in one tenant have zero effect on any other tenant.

If your team introduces a new loan product, adjusts a fee structure, or enables a new business event type in one tenant, no other tenant is affected. This makes it safe for different institutions sharing the same platform to evolve their configurations independently, on their own timelines, without coordination.

Per-Tenant Timezone

Each tenant operates in its own timezone. COB processing, interest calculations, repayment schedule generation, and date-based reporting all use the timezone configured for that tenant - regardless of where the servers are hosted.

This is particularly important for platforms serving institutions across multiple countries or time zones. An institution in Nairobi and one in Dhaka on the same platform can each have their own business day boundaries, end-of-day processing windows, and reporting periods without any conflict.

The Finecko Hub

In a standard Apache Fineract deployment, adding a new tenant requires a database administrator to write SQL directly into the tenant registry, restart the application, and wait for database migrations to complete. There is no built-in interface for this.

Finecko Hub is the tenant management layer that removes this complexity. The Hub provides a web interface and a REST API that handle the complete tenant lifecycle without requiring direct database access or server restarts.

Creating a Tenant

Through the Hub, creating a tenant takes a form or a single API call. You provide a tenant identifier, a name, and optionally connection pool settings. The Hub then:

1. Validates the identifier and confirms it is unique across the platform
2. Provisions a new isolated database for the tenant
3. Runs the full Fineract schema migration against that database, creating all the tables and seed data the new tenant needs
4. Registers the tenant in the platform's central registry
5. Restarts the relevant application services so they pick up the new tenant

The entire process is automated and asynchronous. You can check the status of a provisioning operation at any time through the Hub's status API.

Listing and Managing Tenants

The Hub gives you a centralized view of every tenant registered on the platform - their identifiers, names, timezone settings, connection pool configuration, and current operational status. You can retrieve individual tenant details or the full list at any point.

Deleting a Tenant

When a tenant needs to be decommissioned, the Hub handles the removal cleanly: dropping the tenant's database, removing the registry entry, and restarting the affected services. Tenant deletion can be disabled at the platform level if you want to prevent accidental removal of live environments.

Connection Pool Monitoring

The Hub continuously monitors the database connection pool health for every tenant on the platform. It collects connection utilization metrics from each Fineract instance every minute and raises an alert when any tenant's pool reaches 70% capacity - before connections run out and requests start failing.

Alerts are delivered via AWS SNS, so your operations team can be notified through email, SMS, PagerDuty, or any other system connected to your notification pipeline.

Thread Pool Monitoring

Alongside connection monitoring, the Hub tracks Fineract's HTTP thread pool utilization. A warning is raised when threads reach 60% of capacity, and an action-required alert fires at 75%. This gives your operations team early warning of traffic spikes or runaway processes before they affect response times.

API-First Design

Every operation available in the Hub's interface is also available via its REST API. This means tenant lifecycle management can be embedded directly in your own customer onboarding workflows, provisioning scripts, or internal tools. Creating a new tenant for a newly signed customer can be a single API call from your CRM or billing system.

Upgrading All Tenants Simultaneously

When a new version of Fineract is deployed, the platform's database migration system automatically runs any pending schema changes against every registered tenant's database. All tenants are upgraded in the same deployment cycle, from the same migration scripts, with no per-tenant manual intervention.

This is what makes centralized operations viable at scale. A team managing a platform with dozens or hundreds of tenants can release a version upgrade and know that every tenant is on the new version immediately after the deployment completes.

For the technical configuration details of how multi-tenancy works at the environment variable and database level, see the Multi-Tenancy Configuration guide.