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

# Multi-tenancy

Databunker Pro supports multi-tenancy, allowing you to manage multiple tenants within a single instance. This document outlines the API endpoints for creating, managing, and interacting with tenants.

**Note:** Multi-tenancy is supported on PostgreSQL, MySQL, and Oracle. On PostgreSQL it is enforced with native row-level security (RLS) — see [Database-level tenant isolation](#database-level-tenant-isolation).

> [!TIP]
>
> **Multi-tenancy is per-instance.** All tenants live inside the same Databunker Pro deployment and share the same physical region. If you need to keep PII inside different *legal jurisdictions* — for example because of GDPR cross-border rules, India's DPDPA, Russia's 152-FZ, or similar — multi-tenancy is not the right tool. Instead, run one Databunker Pro instance per jurisdiction and unify operations via Databunker DPO. See [Multi-jurisdiction deployment](https://docs.databunker.org/pro/concepts/global-deployment.md).

## Create Tenant

Creates a new tenant in the Databunker Pro system.

```bash theme={null}
curl -H 'X-Bunker-Token: ROOT-ACCESS-TOKEN' -X POST /v2/TenantCreate \
     --data '{"tenantorg":"testorg","tenantname":"testname"}'
```

### Request Body

| Field | Type | Description |
| - | - | - |
| tenantname | string | The name of the tenant. Must match the format: \[a-z0-9]+ |
| tenantorg | string | The organization slug associated with the tenant |

### Response

| Field | Type | Description |
| - | - | - |
| status | string | Operation status ("ok" if successful) |
| xtoken | string | Tenant access token in UUID format |

### Example Response

```json theme={null}
{
  "status": "ok",
  "xtoken": "TENANT-ACCESS-TOKEN"
}
```

### Notes

* The `TENANT-ACCESS-TOKEN` is a special token to authenticate all tenant related commands. For example create user records.

## Create a Tenant User Account

You have two methods to specify the tenant name: you can either use the `X-Bunker-Tenant` HTTP header or include the tenant name in the hostname. If the `X-Bunker-Tenant` header is missing, Databunker Pro will attempt to retrieve the tenant name from the subdomain in the hostname. If neither option is available, a **default** tenant is used.

Example commands:

```bash theme={null}
curl -H 'X-Bunker-Token: XXXXXXX' \
     -H 'X-Bunker-Tenant: TENANT-NAME' \
     -H 'Content-Type: application/json' \
     -X POST 'http://localhost:3000/v2/UserCreate' \
     --data '{"profile":{"firstname":"John","lastname":"Doe","email":"user@email.com","login":"john"}}'
```

```bash theme={null}
curl -H 'X-Bunker-Token: XXXXXXX' \
     -X POST https://TENANT-NAME.databunker-domain.com/v2/UserCreate \
     --data '{"profile":{"firstname":"John","lastname":"Doe","email":"user@email.com","login":"john"}}'
```

### Notes

* Replace `TENANT-NAME` in the URL with the actual name of the tenant.
* The request body and response format are identical to the standard `UserCreate` call — see the [API Reference](https://docs.databunker.org/pro/api/overview.md). The only difference is the tenant context supplied via the `X-Bunker-Tenant` header or the subdomain.

## Rename Tenant

Renames an existing tenant.

```bash theme={null}
curl -H 'X-Bunker-Token: TENANT-ACCESS-TOKEN' \
     -X POST https://old-tenant.databunker-domain.com/v2/TenantUpdate \
     --data '{"tenantname":"new-name"}'
```

### Request Body

| Field | Type | Description |
| - | - | - |
| tenantname | string | The new name for the tenant. Must match the format: \[a-z0-9]+ |

### Example Request

```json theme={null}
{
  "tenantname": "new-name"
}
```

### Response

| Field | Type | Description |
| - | - | - |
| status | string | Operation status ("ok" if successful) |

### Example Response

```json theme={null}
{
  "status": "ok"
}
```

### Other commands:

For a full list of API requests, check out the [API Reference](https://docs.databunker.org/pro/api/overview.md).

## General Notes

1. **Tenant Name Format**: Tenant names must follow the format `[a-z0-9]+`. This means they can only contain lowercase letters and numbers.

2. **Tenant-Specific URLs**: After creating a tenant, you'll interact with tenant-specific endpoints using URLs in the format `https://tenant-name.databunker-domain.com/...`.

3. **Authentication**: Most endpoints will require the `TENANT-ACCESS-TOKEN` for authentication. Include this token in the `X-Bunker-Token` header or as specified in the Databunker Pro documentation.

4. **SSL/TLS**: Always use HTTPS for secure communication with the API endpoints.

For more detailed information on request/response formats, additional endpoints, or error handling, please refer to the complete Databunker Pro API documentation.

## Database-level tenant isolation

On PostgreSQL, tenant isolation is enforced by the database itself rather than by the correctness of the queries Databunker Pro issues. Two dedicated roles are created during setup, both `NOSUPERUSER NOLOGIN` — neither can log into the database directly, and both are reachable only through `SET ROLE` inside Databunker Pro's own session.

| Role | Privileges | Used for |
| - | - | - |
| `mtenant` | No `BYPASSRLS` — bound by row-level security on every tenant-scoped table | All ordinary traffic |
| `madmin` | `BYPASSRLS`, granted `SELECT` on the `users` table only | The cross-tenant System Operations below |

### How mtenant scoping works

Every tenant-scoped table has row-level security enabled, with a policy tying each row to the tenant set on the current session:

```sql theme={null}
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
CREATE POLICY users_policy ON users FOR ALL TO mtenant
  USING (current_setting('my.tenantid')::int = tenantid);
```

Each request selects the role and the tenant before touching any data:

```sql theme={null}
SET ROLE mtenant; SET my.tenantid=42;
```

From that point the database filters rows itself, so a query that omits its tenant condition — or gets it wrong — still cannot return another tenant's records. This is defence in depth: isolation does not depend on every query being written correctly. Roughly two dozen tables are covered, including `users`, `userapps`, `audit`, `sessions`, `agreements`, `files`, `tokens`, and the versioning tables.

The connection default is `mtenant` with `my.tenantid=1`, so a session gets the restricted role unless something explicitly changes it.

> [!NOTE]
>
> The `xtokens` table is intentionally **not** under RLS. An incoming API token must be resolved to a tenant before the tenant is known, so that lookup cannot itself be tenant-scoped. Tokens carry their tenant binding, which is then applied to every subsequent query in the request.

### How madmin is constrained

The cross-tenant System Operations below necessarily bypass RLS, so two grants keep that bypass narrow: `madmin` holds **`SELECT` only**, and **only on the `users` table**. Even on the bypass path it cannot write anything, and cannot read audit records, sessions, files, or any other table.

### MySQL and Oracle

Multi-tenancy is supported on both, but neither uses a database-enforced equivalent of RLS: there, tenant scoping is applied in the queries Databunker Pro issues. The isolation model is identical from the API's point of view, without this second, database-level line of defence.

## Cross-tenant System Operations

Databunker Pro provides a dedicated **System Operations** API for cross-tenant queries. These endpoints are used for compliance workflows that span the entire deployment — DSAR fulfillment, regulator queries, right-to-erasure, and forensic investigations — where the answer to *"find every record about this person across all our tenants"* must come from one call rather than N tenant-by-tenant queries.

### Access control

All System Operations endpoints are:

* **Restricted to the main tenant admin (`tenantID = 1`)** — the highest-privilege principal of the deployment. Tenant-level admins cannot invoke these endpoints.
* **Gated by a `bulkListUnlock` UUID** — short-lived, must be obtained via `/v2/BulkListUnlock` immediately before the call. This is the same default-deny mechanism used for bulk operations: an admin token alone is not enough.
* **Audited on every call.**

### Endpoints

| Endpoint | Purpose |
| - | - |
| `POST /v2/SystemGetUserProfiles` | Retrieve all profiles for a user (identified by `email` / `phone` / `login` / `custom`) across every tenant. |
| `POST /v2/SystemSearchUserProfiles` | Fuzzy-search for user profiles across every tenant. Mode is auto-detected from the identity value. |
| `POST /v2/SystemDeleteUserProfiles` | Delete all profiles for a user across every tenant — or restrict to a single tenant via `tenantid` / `tenantname`. |
| `POST /v2/SystemRestoreUserProfile` | Restore a previously-deleted user profile for a specific tenant from version history. |

Every response includes the originating `tenantid` and `tenantname` for each profile, so the caller can see exactly which tenants the person appeared in.

### Example: find a user across every tenant

```bash theme={null}
# Step 1: obtain a short-lived unlock UUID
UNLOCK=$(curl -s -X POST https://your-databunker-instance/v2/BulkListUnlock \
  -H "X-Bunker-Token: MAIN_ADMIN_TOKEN" | jq -r .unlockuuid)

# Step 2: cross-tenant lookup
curl -X POST https://your-databunker-instance/v2/SystemGetUserProfiles \
  -H "X-Bunker-Token: MAIN_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"mode\": \"email\",
    \"identity\": \"john.doe@example.com\",
    \"unlockuuid\": \"$UNLOCK\"
  }"
```

### Example response

```json theme={null}
{
  "status": "ok",
  "total": 3,
  "rows": [
    { "tenantid": 7, "tenantname": "student-services", "token": "abc-...", "profile": { "...": "..." } },
    { "tenantid": 9, "tenantname": "analytics",        "token": "def-...", "profile": { "...": "..." } },
    { "tenantid": 12,"tenantname": "alumni",           "token": "ghi-...", "profile": { "...": "..." } }
  ]
}
```

The same person appears under three different tokens — one per tenant — which is the expected outcome of the per-tenant uniqueness model. The System Operations response is the only place these tokens are correlated, and the correlation is audited.

## Next steps

* [Access control](https://docs.databunker.org/pro/administration/access-control.md) — policies and roles within a tenant
* [Sub-accounts](https://docs.databunker.org/pro/concepts/sub-accounts.md) — choosing between tenants and groups
* [Multi-jurisdiction deployment](https://docs.databunker.org/pro/concepts/global-deployment.md) — when a separate instance beats a separate tenant


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.