Skip to Content

Authentication

Create a guest token

Mint a short-lived token that lets one of your customers view your embedded dashboards and metrics.

POST
/api/v2/guest-token/create

Your backend calls this endpoint when a customer opens a page with an embed. Pass the returned token to the Databrain web component.

curl --request POST https://api.usedatabrain.com/api/v2/guest-token/create \  --header "Authorization: Bearer $DATABRAIN_API_TOKEN" \  --header "Content-Type: application/json" \  --data '{    "clientId": "acme",    "dataAppName": "Customer analytics",    "expiryTime": 3600000,    "params": { "userIdentifier": "jane@acme.com" }  }'

Before you start

  • You have a data app API token for the data app. A service token does not work here. See Authentication.
  • Your plan includes embedding (Enterprise, a trial, or self-hosted).

Authorization

DataAppApiToken
headerAuthorizationBearer <token>

A data app API token. A service token is refused.

Body

Only clientId and dataAppName are required. The body is validated strictly: an unknown field returns 400 INVALID_REQUEST_BODY. dataAppId, client_id, tenant_id, workspaceName and permissions.dashboards are not fields.

clientIdstringrequired

The tenant whose rows this viewer sees. It is not a person's id: every user of the same customer gets the same clientId. See the table below.

dataAppNamestringrequired

The data app's name exactly as saved, with its spaces and capital letters. Must belong to the data app of your API token.

expiryTimenumber | string

Lifetime in milliseconds from now, for example 3600000 for one hour. Must be positive. Default: 24 hours.

Default: 86400000

Multi-datasource workspaces: the datasource this viewer queries.

Multi-datamart workspaces: the datamart this viewer queries. Ignored when datasourceName is set.

paramsobject

Filters, visibility and viewer settings.

10 fields in params

The person viewing, for example an email. Their private metrics and saved views follow this value.

timezonestring

IANA time zone for date filters and date grouping, for example America/New_York

Embed ids this token may open. Other embeds of the data app are refused.

appFiltersobject[]

Fixed filter values per metric: { "metricId": "...", "values": { "<filter name>": <value> } }

2 fields in appFilters
metricIdstringrequired
valuesobjectrequired

Fixed dashboard filter values: { "dashboardId": "...", "values": { ... }, "isShowOnUrl": false }

3 fields in dashboardAppFilters
dashboardIdstringrequired
valuesobjectrequired
rlsSettingsobject[]

Row-level security values per metric: { "metricId": "...", "values": { ... } }

2 fields in rlsSettings
metricIdstringrequired
valuesobjectrequired

A filter on one table column for every query: { "tableName": "schema.table", "columnName": "region", "values": ["EU"] }. Up to 50 entries, 1 to 1,000 values each, one entry per column.

Max items: 50
3 fields in tableAppFilters
tableNamestringrequired
Max length: 256Pattern: ^[^\s"'`\[\];.\\]+(\.[^\s"'`\[\];.\\]+)+$
columnNamestringrequired
Max length: 128Pattern: ^[^"'`\[\];.\\]+$
valuesstring | number[]required
Min items: 1Max items: 1000

Metrics to hide on a dashboard: { "dashboardId": "...", "metricIds": ["..."] }

2 fields in hideDashboardMetrics
dashboardIdstringrequired
metricIdsstring[]required

Dashboard filter names to hide.

Filter controls.

7 fields in accessPermissions

The viewer can add dashboard filters.

The viewer can add metric filters.

The viewer can rename dashboard filters.

The viewer can rename metric filters.

Columns the viewer can filter dashboards on: { "tableName": "...", "columns": ["..."] }

2 fields in dashboardFilterColumns
tableNamestringrequired
columnsstring[]required

Columns the viewer can filter metrics on, same shape.

2 fields in metricFilterColumns
tableNamestringrequired
columnsstring[]required

Table tenancy: add the tenant filter to every table that has the tenant column.

What the viewer can do in the embed.

10 fields in permissions

The viewer can archive metrics.

The viewer can manage metrics.

The viewer can create dashboard views.

The viewer can edit metrics.

The viewer can change the dashboard layout.

The viewer can see the underlying data.

The viewer can download metrics.

The viewer can see the sidebar.

The viewer can see the dashboard name.

When true, the viewer cannot create metrics.

What to send as clientId

Tenancy of the datamartclientId
Row per tenant (a tenant column)The tenant column value for this customer, exactly as stored, for example "104"
Schema or database per tenantThe tenant's schema or database name, as mapped in the datamart
Datasource per tenantThe tenant name mapped to that customer's datasource
No tenancyAny non-empty string, for example "None". It is not used

Take the value from your server session, never from the browser. "104" and "0104" are different tenants. A value that matches no tenant returns 400 CLIENT_ID_ERROR; it never widens access.

Expiry

  • A company on the current plans gets a token that lives at most 24 hours. A longer expiryTime is not refused: the token gets 24 hours, and expireAt in the response shows the real expiry.
  • Legacy contracts and self-hosted installs get the expiryTime you send. Self-hosted can change the default with GUEST_TOKEN_DEFAULT_EXPIRY_MS.

Response

{  "token": "5b0c8e3a-2f1d-4c6b-9e7a-8d4f2a1b3c5d",  "expireAt": "2026-11-20T10:00:00.000Z"}
FieldTypeDescription
tokenstringThe guest token. Pass it to the web component
expireAtstring or nullWhen the token expires (ISO 8601). It can be earlier than you asked

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing, unknown, or of the wrong type. expiryTime is not a positive number. timezone is not a valid time zone
400INVALID_DATA_APP_NAMENo data app has this name
400AUTHENTICATION_ERRORThe API token does not belong to this data app, or it is a service token
400CLIENT_ID_ERRORThe clientId matches no tenant. hint says what the tenancy expects
400DATASOURCE_NAME_ERRORNo datasource has this datasourceName
400DATAMART_NAME_ERRORNo datamart has this datamartName
400APP_FILTER_PARAM_ERRORAn appFilters entry is not valid
400RLS_SETTINGS_PARAM_ERRORAn rlsSettings entry is not valid
400DASHBOARD_PARAM_ERROR or INVALID_METRIC_IDA hideDashboardMetrics entry names a dashboard or metric outside this data app
403entitlement_requiredYour plan does not include embedding
503CLIENT_ID_ERRORDatabrain could not check the clientId right now. No token was made. Try again
503entitlement_check_unavailableDatabrain could not check your plan. Try again

For errors that every endpoint returns, see Authentication.

Older version

POST /api/v1/guest-token/create still works for older integrations. It takes workspaceName instead of dataAppName and refuses a data app API token. It also needs embedding on your plan. Use v2 for new code. See the API migration guide.

Next, embed the dashboard with the token.

Example Request
curl -X POST 'https://api.usedatabrain.com/api/v2/guest-token/create' \  -H 'Content-Type: application/json' \  -d '{  "clientId": "acme",  "dataAppName": "Customer analytics",  "expiryTime": 3600000,  "params": {    "userIdentifier": "jane@acme.com"  }}'
Example Response
{  "token": "5b0c8e3a-2f1d-4c6b-9e7a-8d4f2a1b3c5d",  "expireAt": "2026-11-20T10:00:00.000Z"}