Authentication
Create a guest token
Mint a short-lived token that lets one of your customers view your embedded dashboards and metrics.
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).
DataAppApiTokenAuthorizationBearer <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.
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.
The data app's name exactly as saved, with its spaces and capital letters. Must belong to the data app of your API token.
Lifetime in milliseconds from now, for example 3600000 for one hour. Must be positive. Default: 24 hours.
86400000Multi-datasource workspaces: the datasource this viewer queries.
Multi-datamart workspaces: the datamart this viewer queries. Ignored when datasourceName is set.
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.
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.
Fixed filter values per metric: { "metricId": "...", "values": { "<filter name>": <value> } }
Fixed dashboard filter values: { "dashboardId": "...", "values": { ... }, "isShowOnUrl": false }
3 fields in dashboardAppFilters
Row-level security values per metric: { "metricId": "...", "values": { ... } }
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.
503 fields in tableAppFilters
256Pattern: ^[^\s"'`\[\];.\\]+(\.[^\s"'`\[\];.\\]+)+$128Pattern: ^[^"'`\[\];.\\]+$1Max items: 1000Metrics to hide on a dashboard: { "dashboardId": "...", "metricIds": ["..."] }
2 fields in hideDashboardMetrics
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": ["..."] }
Columns the viewer can filter metrics on, same shape.
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 datamart | clientId |
|---|---|
| Row per tenant (a tenant column) | The tenant column value for this customer, exactly as stored, for example "104" |
| Schema or database per tenant | The tenant's schema or database name, as mapped in the datamart |
| Datasource per tenant | The tenant name mapped to that customer's datasource |
| No tenancy | Any 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
expiryTimeis not refused: the token gets 24 hours, andexpireAtin the response shows the real expiry. - Legacy contracts and self-hosted installs get the
expiryTimeyou send. Self-hosted can change the default withGUEST_TOKEN_DEFAULT_EXPIRY_MS.
Response
{ "token": "5b0c8e3a-2f1d-4c6b-9e7a-8d4f2a1b3c5d", "expireAt": "2026-11-20T10:00:00.000Z"}| Field | Type | Description |
|---|---|---|
token | string | The guest token. Pass it to the web component |
expireAt | string or null | When the token expires (ISO 8601). It can be earlier than you asked |
Errors
| Status | error.code | Why |
|---|---|---|
| 400 | INVALID_REQUEST_BODY | A field is missing, unknown, or of the wrong type. expiryTime is not a positive number. timezone is not a valid time zone |
| 400 | INVALID_DATA_APP_NAME | No data app has this name |
| 400 | AUTHENTICATION_ERROR | The API token does not belong to this data app, or it is a service token |
| 400 | CLIENT_ID_ERROR | The clientId matches no tenant. hint says what the tenancy expects |
| 400 | DATASOURCE_NAME_ERROR | No datasource has this datasourceName |
| 400 | DATAMART_NAME_ERROR | No datamart has this datamartName |
| 400 | APP_FILTER_PARAM_ERROR | An appFilters entry is not valid |
| 400 | RLS_SETTINGS_PARAM_ERROR | An rlsSettings entry is not valid |
| 400 | DASHBOARD_PARAM_ERROR or INVALID_METRIC_ID | A hideDashboardMetrics entry names a dashboard or metric outside this data app |
| 403 | entitlement_required | Your plan does not include embedding |
| 503 | CLIENT_ID_ERROR | Databrain could not check the clientId right now. No token was made. Try again |
| 503 | entitlement_check_unavailable | Databrain 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.
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" }}'{ "token": "5b0c8e3a-2f1d-4c6b-9e7a-8d4f2a1b3c5d", "expireAt": "2026-11-20T10:00:00.000Z"}