Authentication
Authenticate API requests
Send a service token or a data app API token with every request to the Databrain API.
Every request to the Databrain API sends one token in the Authorization header. Your backend sends it. Never put a token in browser code.
curl https://api.usedatabrain.com/api/v2/workspace \
--header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN"Base URL
| Deployment | Base URL |
|---|---|
| Databrain cloud | https://api.usedatabrain.com |
| Self-hosted | The URL of your Databrain backend, for example https://databrain-api.example.com |
All paths in this reference start with /api/v2. They are the same on cloud and self-hosted.
Pick the token
| Token | Scope | Where you get it | Use it for |
|---|---|---|---|
| Service token | Your whole organization | Settings > Developers > Tokens, tab Service Tokens, then Generate service token | Datasources, datamarts, semantic layers, workspaces, data apps, API tokens, allowed domains, SMTP settings, dashboard import and export |
| Data app API token | One data app | Data Apps, open the data app, tab API tokens, then Generate API token | Guest tokens, embeds and scheduled reports of that data app, and its data retrieval endpoints |
Self-hosted: you can also make a service token with the API. See Create a service token.
Some endpoints accept only a service token. A data app API token gets 403 on them:
POST,GET,PUTandDELETE /api/v2/data-app(data app CRUD)POSTandGET /api/v2/data-app/api-tokensPOST /api/v2/data-app/export-dashboardandPOST /api/v2/data-app/import-dashboard- Every method on
/api/v2/data-app/datamarts/semantic-layer
Guest tokens and the embed endpoints work only with a data app API token, because the token names the data app. A service token gets 400 INVALID_DATA_APP_API_KEY on the embed endpoints.
The token is shown once
A token is a UUID, for example 3f9a1c2e-8b7d-4e6f-9a0b-1c2d3e4f5a6b. Databrain stores only a hash of it, so you see the full token only when you create or rotate it. Copy it then and keep it in your secret store.
The token list shows keyLast4, the last 4 characters, and keyId, a public id. Neither is a credential. If you lose a token, rotate it or make a new one.
Plan
Endpoints that create embed access need embedding on your plan: create a guest token, create a data app, create an API token, create or update an embed, and check embed access. Embedding is on the Enterprise plan, on a trial, and on self-hosted. Without it they return 403 entitlement_required. Reading, renaming and deleting what you already have keeps working.
Errors on every endpoint
Every error has this shape. Some errors also have hint and details.
{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "API Key is invalid or expired!"
}
}| Status | error.code | Why | Fix |
|---|---|---|---|
| 400 | AUTHENTICATION_ERROR | No Authorization: Bearer header, or the token is not a UUID | Send Authorization: Bearer <token> |
| 401 | AUTHENTICATION_ERROR | The token is unknown, revoked or expired | Use a current token |
| 401 | AUTHENTICATION_ERROR | The token lacks the Access Metrics and Access Dashboards scopes | Make a new token |
| 403 | AUTHENTICATION_ERROR | A data app API token on a service-token endpoint | Use a service token |
| 403 | entitlement_required | The plan does not include embedding | See Plan |
| 400 or 403 | UNSUBSCRIBED_ACCOUNT_ERROR or TRIAL_ENDED | The trial ended | Choose a plan in Settings > Billing |
| 400 | LICENSE_EXPIRED | Self-hosted only: the licence key expired | Renew the licence key |
| 403 | ACCOUNT_DISABLED or COMPANY_DELETION_SCHEDULED | The organization is disabled or locked for deletion | Contact Databrain support |
| 429 | COMMERCIAL_LIMIT_EXCEEDED | The organization used its API call limit for the period | Wait for the next period, or change plan |
| 500 | INTERNAL_SERVER_ERROR | Databrain failed | Try again. If it fails again, contact support |
| 503 | COMMERCIAL_UNAVAILABLE or entitlement_check_unavailable | Databrain could not check your plan | Try again |
The entitlement_required error names the reason:
{
"error": {
"code": "entitlement_required",
"message": "Embedding needs the Enterprise plan. This workspace is on Team.",
"capability": "embed",
"currentPlan": "team",
"requiredPlan": "enterprise"
}
}Next, create a guest token.