Multi-Tenancy

Every deployment of Kora Digital Banking serves multiple tenants from a single codebase. Each tenant gets an isolated database schema, branded UI, and its own configuration — while sharing the same infrastructure.

Tenant Detection

The API resolves the current tenant using the following priority order:

Priority	Method	Example
1	JWT tenantId claim	Embedded in access token
2	X-Tenant-ID header	X-Tenant-ID: fmfb
3	Subdomain	fmfb.korastratum.com
4	Query parameter	?tenant=fmfb
5	Default tenant	DEFAULT_TENANT env var

For server-to-server integrations, always send the X-Tenant-ID header explicitly.

Database Isolation

┌─────────────────────────────────┐
│         PostgreSQL               │
│                                  │
│  ┌────────────────┐             │
│  │ platform.*     │  tenants,   │
│  │                │  feature    │
│  │                │  flags      │
│  └────────────────┘             │
│                                  │
│  ┌────────────────┐  ┌────────┐ │
│  │ tenant_fmfb.*  │  │ tenant │ │
│  │  users         │  │ _acme  │ │
│  │  wallets       │  │  .*    │ │
│  │  transfers     │  │        │ │
│  │  loans         │  │        │ │
│  │  savings       │  │        │ │
│  └────────────────┘  └────────┘ │
└─────────────────────────────────┘

• platform.* — Shared metadata: tenant list, feature flags, global configuration.
• tenant_<name>.* — Per-tenant tables: users, wallets, transfers, loans, savings, notifications, and more.
• Row-level security — PostgreSQL policies enforce that queries only return data belonging to the authenticated tenant.

Tenant Object

After detection, the middleware attaches a tenant object to every request:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "fmfb",
  "displayName": "First Microfinance Bank",
  "status": "active",
  "tier": "enterprise",
  "subdomain": "fmfb",
  "customDomain": "bank.fmfb.com",
  "configuration": {
    "transfersEnabled": true,
    "loansEnabled": true,
    "savingsEnabled": true,
    "billPaymentsEnabled": true,
    "internationalTransfersEnabled": false
  },
  "branding": {
    "primaryColor": "#6B46C1",
    "secondaryColor": "#10B981",
    "logoUrl": "https://cdn.korastratum.com/fmfb/logo.png"
  },
  "securitySettings": {
    "mfaRequired": false,
    "sessionTimeout": 1800,
    "maxConcurrentSessions": 5
  }
}

Tenant Tiers

Tier	Rate Limit (15 min)	Features
starter	100 requests	Core banking (accounts, transfers)
pro	500 requests	+ Loans, savings, bill payments
enterprise	2,000 requests	+ International transfers, custom domains, dedicated support

Theme Endpoint

The theme endpoint is public (no authentication required) and returns tenant branding for client apps:

GET /api/v1/theme?tenant=fmfb

{
  "tenantId": "550e8400-...",
  "brandName": "First Microfinance Bank",
  "currency": "NGN",
  "colors": {
    "primary": "#6B46C1",
    "secondary": "#10B981",
    "background": "#FFFFFF",
    "text": "#1A1A2E"
  },
  "typography": {
    "fontFamily": "Inter, sans-serif"
  }
}

Mobile and web clients call this endpoint at startup to apply tenant-specific branding before the user logs in.

Feature Flags

Tenant configuration includes feature flags that control which product modules are available:

Flag	Description
transfersEnabled	Internal and external transfers
loansEnabled	Loan applications and management
savingsEnabled	Savings products
billPaymentsEnabled	Bill payments and top-ups
internationalTransfersEnabled	SWIFT transfers
aiInsightsEnabled	AI-powered spending insights

Requests to disabled features return 403 Forbidden with code FEATURE_DISABLED.

Next Steps

• Authentication — How JWT tokens carry the tenantId claim.
• API Reference — Headers and environment configuration.
• Server Integration — Adding tenant middleware to your backend.