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.

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.

Create Tenant

Creates a new tenant in the Databunker Pro system.

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

{
  "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:

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"}}'

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. The only difference is the tenant context supplied via the X-Bunker-Tenant header or the subdomain.

Rename Tenant

Renames an existing tenant.

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

{
  "tenantname": "new-name"
}

Response

Field	Type	Description
status	string	Operation status (“ok” if successful)

Example Response

{
  "status": "ok"
}

Other commands:

For a full list of API requests, check out the API Reference.

General Notes

Tenant Name Format: Tenant names must follow the format [a-z0-9]+. This means they can only contain lowercase letters and numbers.
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/....
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.
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:

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:

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.

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

# 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

{
  "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 — policies and roles within a tenant
Sub-accounts — choosing between tenants and groups
Multi-jurisdiction deployment — when a separate instance beats a separate tenant

Get started

Installation

Administration

Concepts

Comparisons

Migrations

How-tos

Developer tools

Create Tenant

Request Body

Response

Example Response

Notes

Create a Tenant User Account

Notes

Rename Tenant

Request Body

Example Request

Response

Example Response

Other commands:

General Notes

Database-level tenant isolation

How mtenant scoping works

How madmin is constrained

MySQL and Oracle

Cross-tenant System Operations

Access control

Endpoints

Example: find a user across every tenant

Example response

Next steps

​Create Tenant

​Request Body

​Response

​Example Response

​Notes

​Create a Tenant User Account

​Notes

​Rename Tenant

​Request Body

​Example Request

​Response

​Example Response

​Other commands:

​General Notes

​Database-level tenant isolation

​How mtenant scoping works

​How madmin is constrained

​MySQL and Oracle

​Cross-tenant System Operations

​Access control

​Endpoints

​Example: find a user across every tenant

​Example response

​Next steps

Create Tenant

Request Body

Response

Example Response

Notes

Create a Tenant User Account

Notes

Rename Tenant

Request Body

Example Request

Response

Example Response

Other commands:

General Notes

Database-level tenant isolation

How mtenant scoping works

How madmin is constrained

MySQL and Oracle

Cross-tenant System Operations

Access control

Endpoints

Example: find a user across every tenant

Example response

Next steps