Skip to Content

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

DeploymentBase URL
Databrain cloudhttps://api.usedatabrain.com
Self-hostedThe 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

TokenScopeWhere you get itUse it for
Service tokenYour whole organizationSettings > Developers > Tokens, tab Service Tokens, then Generate service tokenDatasources, datamarts, semantic layers, workspaces, data apps, API tokens, allowed domains, SMTP settings, dashboard import and export
Data app API tokenOne data appData Apps, open the data app, tab API tokens, then Generate API tokenGuest 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, PUT and DELETE /api/v2/data-app (data app CRUD)
  • POST and GET /api/v2/data-app/api-tokens
  • POST /api/v2/data-app/export-dashboard and POST /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!"
  }
}
Statuserror.codeWhyFix
400AUTHENTICATION_ERRORNo Authorization: Bearer header, or the token is not a UUIDSend Authorization: Bearer <token>
401AUTHENTICATION_ERRORThe token is unknown, revoked or expiredUse a current token
401AUTHENTICATION_ERRORThe token lacks the Access Metrics and Access Dashboards scopesMake a new token
403AUTHENTICATION_ERRORA data app API token on a service-token endpointUse a service token
403entitlement_requiredThe plan does not include embeddingSee Plan
400 or 403UNSUBSCRIBED_ACCOUNT_ERROR or TRIAL_ENDEDThe trial endedChoose a plan in Settings > Billing
400LICENSE_EXPIREDSelf-hosted only: the licence key expiredRenew the licence key
403ACCOUNT_DISABLED or COMPANY_DELETION_SCHEDULEDThe organization is disabled or locked for deletionContact Databrain support
429COMMERCIAL_LIMIT_EXCEEDEDThe organization used its API call limit for the periodWait for the next period, or change plan
500INTERNAL_SERVER_ERRORDatabrain failedTry again. If it fails again, contact support
503COMMERCIAL_UNAVAILABLE or entitlement_check_unavailableDatabrain could not check your planTry 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.

On this page