Skip to main content
Every authenticated API call carries a credential in the X-Bunker-Token header. Databunker Pro has a small hierarchy of credential types, each scoped to a different level of access. This page is the single reference for all of them.

​
Request headers

If X-Bunker-Tenant is omitted, Databunker Pro derives the tenant from the subdomain of the request host (acme.databunker.example.com → tenant acme). Requests to localhost or a bare host resolve to the default tenant.

​
Credential hierarchy

All tokens are stored hashed on the server — a token value is shown exactly once at creation time and cannot be recovered later.

​
Root token

The highest-privilege credential of the deployment, created once at installation:
  • Interactive setup — shown once on the setup completion screen. See Generate admin credentials.
  • Unattended install — returned by the /autoinstall endpoint, which is enabled only while the DATABUNKER_SETUPKEY environment variable is set. See Unattended installation.
Root tokens never expire. Use them for administration and automation, and prefer scoped role xtokens for application traffic.

​
Tenant access token

In multi-tenant deployments, TenantCreate returns an xtoken — the tenant administrator’s credential. It behaves like a root token scoped to that tenant:
The tenant admin passes this token in X-Bunker-Token, together with X-Bunker-Tenant: acme (or the tenant subdomain). See Multi-tenancy.

​
Role xtoken

Scoped service credentials governed by access-control policies. Setup is three calls:
Without finaltime the xtoken expires after 10 minutes. A supplied finaltime is capped by the max_xtoken_retention_period configuration policy.

​
User login xtoken

A short-lived credential that lets an end user act on their own record only (e.g. from the user privacy portal):
Same expiry rules as role xtokens: 10 minutes by default, capped by max_xtoken_retention_period.
For safety, a login xtoken cannot invoke UserDelete, UserUpdate, UserPatch, AppdataUpdate, or AgreementCancel on its own record — these self-service operations must go through an admin or a user request workflow with approval.

​
Bulk-unlock UUID

Bulk read and delete operations are denied by default — an admin token alone is not enough. You must first obtain a short-lived unlock UUID, then pass it with the bulk call:
The unlock UUID lives for 60 seconds and may be reused within that window. It applies to BulkList*, BulkDeleteTokens, UserSearch, and the cross-tenant System* lookups. See Select security for the design rationale.

​
Endpoint permission levels

  • Public endpoints — no token required: UserPrelogin, UserLogin, CaptchaCreate, SharedRecordGet, TenantGetUIConf. Calls to these are not written to the audit trail.
  • Authenticated endpoints — everything else requires X-Bunker-Token and passes policy evaluation: root tokens bypass policy checks, role xtokens are evaluated against their linked policies, and login xtokens are restricted to the user’s own record.
  • Main-tenant-only endpoints — denied to sub-tenant admins even with a valid tenant token: RoleCreate, RoleUpdate, PolicyCreate, PolicyUpdate, TenantListTenants, SystemGenerateWrappingKey, and all cross-tenant System* operations.
Failed authentication returns HTTP 403 with {"status":"error","message":"Access denied"} — see Errors.