Self-Hosted APIs
Create a service token
Set the organization's service token on self-hosted Databrain to a UUID you choose.
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
- Self-hosted only.
- You have an access token from Create the admin account or Create an admin JWT. The user needs permission to create API tokens. Admins have it.
Auth
Authorization: Bearer <accessToken>, the user's access token. A service token or a data app API token does not work here.
AdminJwtAuthorizationBearer <JWT>Self-hosted only: the admin JWT from Create admin JWT.
Body
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"}| Field | Description |
|---|---|
key | The service token, in lower case with hyphens |
keyId | The public id of the token. Use it to rotate as a signed-in user |
keyLast4 | The 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
| Status | error.code | Why |
|---|---|---|
| 400 | INVALID_REQUEST_BODY | token is missing or not a UUID |
| 400 | API_TOKEN_NAME_ALREADY_EXISTS | Another key is named Service Token. Rename it, then try again |
| 400 | LICENSE_EXPIRED | The licence key expired |
| 401 | UNAUTHORIZED | No access token was sent |
| 403 | FORBIDDEN | You do not have permission to create tokens. |
| 500 | SELFHOSTED_APP_ERROR | You called it on Databrain cloud |
| 500 | ACCOUNT_NOT_FOUND or INTERNAL_SERVER_ERROR | The 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.
curl -X POST 'https://databrain-api.example.com/api/v2/service-token' \ -H 'Content-Type: application/json' \ -d '{ "token": "string"}'{ "key": "3f9a1c2e-8b7d-4e6f-9a0b-1c2d3e4f5a6b", "keyId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "keyLast4": "5a6b"}