Skip to Content

Token Management

Set up admin and service tokens

On self-hosted Databrain, create the first admin, sign in and get a service token for the API.

A self-hosted Databrain starts with no users. You create the first admin with the API, then get a service token that calls the rest of the API.

Before you start

  • You run self-hosted Databrain. On Databrain cloud these routes answer “This feature is only available for self-hosted instances”. On cloud, create tokens in Settings > Tokens.
  • Replace <HOST> with your Databrain backend URL.

Steps

  1. Create the first admin with POST <HOST>/api/v2/admin-account. The body has firstName, lastName, email, password and companyName. See Create Admin Account.
  2. Read data.accessToken from the response.
  3. Later, sign in again with POST <HOST>/api/v2/admin-account/jwt and email and password. It also returns data.accessToken. See Create Admin JWT.
  4. Create the service token with POST <HOST>/api/v2/service-token and Authorization: Bearer <accessToken>. The body is { "token": "<a UUID you choose>" }. See Create Service Token.
  5. Store the key from the response in your secret store.

The full API key is shown once, when you create or rotate it. Store it then. Lists show only the last 4 characters (keyLast4).

Which credential does what

CredentialUsed for
Admin access tokenCreating the service token and resetting the admin password
Service tokenCompany API: workspaces, data apps, datamarts, semantic layer
Data app API keyGuest tokens for one data app
Guest tokenThe browser embed, for one client

Rotate a service token

RouteAuthorizationUse it when
POST /api/v2/service-token/rotateBearer <the service token>The token is alive and has no expiry yet
POST /api/v2/service-token/rotate-from-appBearer <admin access token>, body tokenIdThe token is expired, already retiring, or lost

Both take expireAt: how many seconds the old key keeps working. 0 stops it at once. Both return the new key, keyId and keyLast4. See Rotate Service Token.

Change the admin password

POST <HOST>/api/v2/service-token/reset-password with Authorization: Bearer <admin access token> and currentPassword and password. It returns { "data": { "success": true } }. See Reset Admin Password.

If something goes wrong

  • /admin-account returns HTTP 200 with an error object. These two routes send errors in the body with status 200. Always check for error.
  • 403 FORBIDDEN: “You do not have permission to create tokens.” The signed-in user needs the Create permission for API tokens.
  • 400: “This service token already has an expiry, so it cannot rotate itself. Sign in to Databrain and rotate it from Settings > Tokens.” Use /rotate-from-app instead.
  • 400 INVALID_REQUEST_BODY: "token" must be a valid GUID. Send a UUID in token.