Skip to Content

Self-Hosted APIs

Create a service token

Set the organization's service token on self-hosted Databrain to a UUID you choose.

POST
/api/v2/service-token

You send a UUID. It becomes your organization's service token. Use it for the rest of this API. See Authentication.

curl --request POST https://databrain-api.example.com/api/v2/service-token \  --header "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \  --header "Content-Type: application/json" \  --data "{ \"token\": \"$(uuidgen)\" }"

If the organization already has a service token, the new value replaces it at once. Every integration that uses the old token stops working. To keep the old one working for a while, rotate instead.

Before you start

Auth

Authorization: Bearer <accessToken>, the user's access token. A service token or a data app API token does not work here.

Authorization

AdminJwt
headerAuthorizationBearer <JWT>

Self-hosted only: the admin JWT from Create admin JWT.

Body

tokenstringrequired

The service token you want. Generate a random UUID, for example with uuidgen

Response

{  "key": "3f9a1c2e-8b7d-4e6f-9a0b-1c2d3e4f5a6b",  "keyId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",  "keyLast4": "5a6b"}
FieldDescription
keyThe service token, in lower case with hyphens
keyIdThe public id of the token. Use it to rotate as a signed-in user
keyLast4The last 4 characters

Databrain stores only a hash of the token. A new token is named Service Token and has the Access Metrics and Access Dashboards scopes.

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYtoken is missing or not a UUID
400API_TOKEN_NAME_ALREADY_EXISTSAnother key is named Service Token. Rename it, then try again
400LICENSE_EXPIREDThe licence key expired
401UNAUTHORIZEDNo access token was sent
403FORBIDDENYou do not have permission to create tokens.
500SELFHOSTED_APP_ERRORYou called it on Databrain cloud
500ACCOUNT_NOT_FOUND or INTERNAL_SERVER_ERRORThe token was not saved

An expired access token returns HTTP 200 with { "error": { "code": "UNAUTHORIZED", "message": "jwt expired" } }. Get a new one with Create an admin JWT.

Example Request
curl -X POST 'https://databrain-api.example.com/api/v2/service-token' \  -H 'Content-Type: application/json' \  -d '{  "token": "string"}'
Example Response
{  "key": "3f9a1c2e-8b7d-4e6f-9a0b-1c2d3e4f5a6b",  "keyId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",  "keyLast4": "5a6b"}