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
- Create the first admin with
POST <HOST>/api/v2/admin-account. The body hasfirstName,lastName,email,passwordandcompanyName. See Create Admin Account. - Read
data.accessTokenfrom the response. - Later, sign in again with
POST <HOST>/api/v2/admin-account/jwtandemailandpassword. It also returnsdata.accessToken. See Create Admin JWT. - Create the service token with
POST <HOST>/api/v2/service-tokenandAuthorization: Bearer <accessToken>. The body is{ "token": "<a UUID you choose>" }. See Create Service Token. - Store the
keyfrom 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
| Credential | Used for |
|---|---|
| Admin access token | Creating the service token and resetting the admin password |
| Service token | Company API: workspaces, data apps, datamarts, semantic layer |
| Data app API key | Guest tokens for one data app |
| Guest token | The browser embed, for one client |
Rotate a service token
| Route | Authorization | Use it when |
|---|---|---|
POST /api/v2/service-token/rotate | Bearer <the service token> | The token is alive and has no expiry yet |
POST /api/v2/service-token/rotate-from-app | Bearer <admin access token>, body tokenId | The 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-accountreturns HTTP 200 with anerrorobject. These two routes send errors in the body with status 200. Always check forerror.- 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-appinstead. - 400
INVALID_REQUEST_BODY:"token" must be a valid GUID. Send a UUID intoken.