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

# Automatic provisioning

> How registering a new tenant automatically provisions its databases, message broker, credentials, and migrations — from creation to first operation.

When a new tenant is onboarded, the platform provisions everything that tenant needs to operate in isolation — databases, a message broker, credentials, and schema migrations — without manual database administration for each product.

This page describes the provisioning lifecycle end to end — from tenant creation to active database connections.

<Note>
  Automatic provisioning runs only when `MULTI_TENANT_ENABLED=true`. In single-tenant deployments, products use a single pre-configured database and skip this lifecycle entirely.
</Note>

## The provisioning lifecycle

***

Onboarding a tenant moves through five stages. Each stage builds on the previous one, ending with a tenant that is fully isolated and ready to serve traffic.

<Steps>
  <Step title="Tenant creation">
    A tenant is created with its identity and metadata. At this point the tenant exists as an identity only — the value the `tenantId` JWT claim will resolve to — but has no infrastructure attached yet.
  </Step>

  <Step title="Service registration">
    Each product the tenant will use is registered as a **service** under that tenant — for example, Midaz Ledger or Tracer. The service registration declares the isolation mode (`DATABASE` or `SCHEMA`) and the configuration the platform needs to provision and reach the tenant's resources.
  </Step>

  <Step title="Automatic provisioning of infrastructure">
    Registering a service triggers provisioning of the isolated infrastructure for that tenant:

    * **PostgreSQL** — a dedicated database (in `DATABASE` mode) or a dedicated schema (in `SCHEMA` mode) for relational data.
    * **MongoDB** — an isolated database for document data such as metadata.
    * **RabbitMQ** — isolated messaging resources (virtual host / queues) for the tenant's asynchronous events.

    Credentials for each resource are generated and stored in the **credentials vault**, never embedded in configuration or shared between tenants.
  </Step>

  <Step title="Migrations">
    Once the infrastructure exists, the platform runs the product's schema migrations against the tenant's new database or schema. This brings the tenant's storage to the exact schema version the product expects, so a freshly provisioned tenant is structurally identical to every other tenant on that product.
  </Step>

  <Step title="Start of operation">
    With infrastructure provisioned, credentials vaulted, and migrations applied, the service is marked ready. The product can now resolve the tenant from its JWT, open an isolated connection, and begin serving requests. From this point the tenant operates exactly as described in [Multi-tenancy](/en/multi-tenancy).
  </Step>
</Steps>

## What gets provisioned

***

| Resource        | Purpose                                                                                    | Isolation                                                                 |
| :-------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |
| **PostgreSQL**  | Relational data — organizations, ledgers, accounts, transactions, balances, rules, limits. | Dedicated database (`DATABASE` mode) or dedicated schema (`SCHEMA` mode). |
| **MongoDB**     | Document data such as metadata.                                                            | Dedicated database per tenant.                                            |
| **RabbitMQ**    | Asynchronous events and inter-service messaging.                                           | Isolated virtual host / queues per tenant.                                |
| **Credentials** | Access to the resources above.                                                             | Unique per tenant, stored in the credentials vault.                       |

<Warning>
  Credentials are generated per tenant and stored in the vault. They are never reused across tenants and never shared between isolation modes. See [Security](/en/midaz/security) for rotation and credential-handling guarantees.
</Warning>

## Why provisioning is centralized

***

Previously, provisioning logic lived only inside individual product scopes (such as the Matcher). Centralizing it through the platform layer means:

* **Consistency** — every product provisions a tenant the same way, with the same isolation guarantees and the same migration discipline.
* **One onboarding path** — adding a tenant to a new product is a service registration, not a bespoke database setup.
* **Auditability** — tenant and service lifecycle is tracked in one place rather than scattered across products.

<Tip>
  Because provisioning is tied to service registration, you can onboard a tenant to additional products over time — each new service registration provisions its own isolated infrastructure without touching the tenant's existing data.
</Tip>

## Related pages

***

<CardGroup cols={2}>
  <Card title="Use cases" icon="lightbulb" href="/en/multi-tenancy/use-cases" cta="See examples">
    The tenant and service entities that drive provisioning.
  </Card>

  <Card title="Multi-tenancy" icon="layer-group" href="/en/multi-tenancy" cta="See the overview">
    How isolation modes and tenant scoping work.
  </Card>

  <Card title="Security" icon="shield-halved" href="/en/midaz/security" cta="Read about guarantees">
    Credential vaulting, rotation, and per-tenant resource limits.
  </Card>

  <Card title="Use cases" icon="lightbulb" href="/en/multi-tenancy/use-cases" cta="See examples">
    Choosing an isolation mode for your deployment.
  </Card>
</CardGroup>