> ## 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).

<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](/pro/concepts/global-deployment).
</Tip>

## 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](/pro/api/overview). 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](/pro/api/overview).

## 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.

## 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.