> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verifow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tenant Management

> Understand multi-tenant data isolation, configuration, and deployment

## Overview

Verifow operates as a multi-tenant platform. Each bank or financial institution operates within its own tenant, with complete data isolation from other institutions.

## What Is a Tenant?

A tenant represents your organization within Verifow. All your transactions, cases, rules, reports, and users exist within your tenant boundary.

## Tenant Characteristics

| Feature                    | Description                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------ |
| **Data Isolation**         | Transaction data, cases, and user records are completely isolated from other tenants |
| **Independent Rules**      | Each tenant maintains its own custom rules alongside the shared CBN mandatory rules  |
| **Dedicated Admins**       | Every tenant has `BANK_ADMIN` users who manage day-to-day operations                 |
| **Engine Configuration**   | Risk weights and thresholds can be tuned per tenant                                  |
| **Auto-Seeded Rules**      | New tenants automatically receive the 9 CBN mandatory rules                          |
| **KYC Provider Selection** | Each tenant chooses between embedded providers or BYOL (Bring Your Own License)      |
| **KYC Trust Mode**         | Controls how KYC status is resolved: STRICT, HYBRID, or EXTERNAL                     |
| **BYOL Fallback Mode**     | Defines behavior when the BYOL provider is unavailable                               |

## Data Boundaries

The following data is scoped to your tenant and never shared:

* Transaction screening history
* Compliance cases and notes
* Custom detection rules
* KYC applications and verification results
* KYB applications and corporate verification data
* Regulatory reports
* Audit logs
* User accounts and roles

## KYC Provider Configuration

Each tenant independently controls how customer identity verification is performed.

### Provider Modes

| Mode       | Description                                           | Use Case-                                     |
| ---------- | ----------------------------------------------------- | --------------------------------------------- |
| `EMBEDDED` | Platform-managed providers (primary → fallback chain) | Default — no setup required                   |
| `BYOL`     | Tenant provides their own KYC API credentials         | Institutions with existing provider contracts |

### Configuring BYOL

`BANK_ADMIN` users can configure BYOL from **Dashboard → Settings → KYC Provider**:

1. Select **BYOL** from-he mode dropdown.
2. Enter your prov-er details:
   * **Provider Name** — e.g., "YourProviderName"
   * **Base URL** —-our provider's API root
   * **API Key / App ID** -Authentication credentials
   * **Endpoints** — Paths-or NIN, BVN, and Liveness checks
   * **R-ponse Mapping** — JSON paths to extract first/last names
   * **Match Confidence** — Threshold for name match success (0–100)
3. Save — new verifications immediately use your provider.

The configuration is stored securely as JSON in `Tenant.kycProviderConfig` and is never exposed to other tenants.

## KYC Trust Mode

Controls how KYC status is resolved during transaction screening:

| Mode       | Description                                                            |
| ---------- | ---------------------------------------------------------------------- |
| `STRICT`   | **Default.** KYC records must exist in the DB. Payload KYC is ignored. |
| `HYBRID`   | Uses payload KYC if provided, falls back to DB lookup.                 |
| `EXTERNAL` | Requires KYC status in every transaction payload. No local DB lookup.  |

Managed via `PATCH /api/v1/tenants/me` with `kycTrustMode`.

## BYOL Fallback Mode

Defines behavior when the BYOL provider is unavailable:

| Mode             | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `NONE`           | **Default.** Returns `ServiceUnavailableException`.                    |
| `WALLET_RESERVE` | Falls back to the embedded provider if the wallet has available funds. |

Managed via `PATCH /api/v1/tenants/me` with `byolFallbackMode`.

> **Note:** Tenant-level configuration changes for engine weights or feature flags are handled by platform administrators. Contact your account manager if you need adjustments beyond KYC provider selection.