Token Management
Guest token body fields
Every field you can send to POST /api/v2/guest-token/create, with its type and meaning.
Your backend sends this body to POST https://api.usedatabrain.com/api/v2/guest-token/create with Authorization: Bearer <data app API key>. Databrain refuses any field not on this page.
Minimal body
{
"clientId": "acme-corp",
"dataAppName": "Customer Analytics"
}Top-level fields
| Field | Type | Required | Meaning |
|---|---|---|---|
clientId | string | Yes | The tenant: your customer company, not a person. Its value depends on the tenancy level (see below). |
dataAppName | string | Yes | The data app’s saved name, exactly. Case and spaces count. |
datamartName | string | No | Name of the datamart to use. |
datasourceName | string | No | Name of the datasource to use. |
expiryTime | number or numeric string | No | Token life in milliseconds from now. Default 24 hours. |
params | object | No | Filters, scope and the viewer’s identity. |
permissions | object | No | Turns embed features on or off for this token. |
What to put in clientId
| Tenancy level | clientId value |
|---|---|
| Table | A value in the customer table’s primary key column, for example an org_id |
| Database | The tenant’s schema name |
| Multi-database | The tenant’s database name |
| No tenancy | Still required, but Databrain does not scope by it |
See Tenancy model.
params
| Field | Type | Meaning |
|---|---|---|
userIdentifier | string | The person who views the embed, for example your user ID or email. Metrics they create and their private items belong to this value. It does not scope rows. |
timezone | string | IANA time zone name, for example Asia/Kolkata. See Guest token timezone. |
allowedEmbeds | string[] | Dashboard IDs this token can open. Leave it out to allow every dashboard of the data app. |
appFilters | { metricId, values }[] | Values for metric app filters. See Metric App Filter. |
dashboardAppFilters | { dashboardId, values, isShowOnUrl? }[] | Values for dashboard app filters. See Dashboard App Filter. |
rlsSettings | { metricId, values }[] | Values for row level security filters. Each key in values must be the name of an RLS filter in the workspace. |
tableAppFilters | { tableName, columnName, values }[] | Limits every query that reads a table to rows where the column is one of values. See below. |
hideDashboardMetrics | { dashboardId, metricIds[] }[] | Hides these metrics on that dashboard. |
hideDashboardFilters | string[] | Hides dashboard filters with these labels. |
accessPermissions | object | Filter permissions and auto client scope. See below. |
tableAppFilters rules
tableNameisschema.table, as the datamart shows it. No quotes or spaces.columnNameis a plain column name. No quotes or dots.valuesholds 1 to 1000 strings or numbers.- At most 50 entries, and one entry per table column.
A query that reads the table in a way Databrain cannot filter is refused. It never runs unfiltered.
accessPermissions
| Field | Type | Meaning |
|---|---|---|
isAllowEndUserDashboardFilter | boolean | Viewers can add dashboard filters |
isAllowDashboardFilterNameChange | boolean | Viewers can rename dashboard filters |
isAllowEndUserMetricFilter | boolean | Viewers can add metric filters |
isAllowMetricFilterNameChange | boolean | Viewers can rename metric filters |
dashboardFilterColumns | { tableName, columns[] }[] | Columns viewers can use in dashboard filters |
metricFilterColumns | { tableName, columns[] }[] | Columns viewers can use in metric filters |
isAllowAutoClientScope | boolean | Table tenancy only. Adds client column = clientId to every datamart table with a client column. A query it cannot scope is refused. |
permissions
When the token sets a flag, it wins over the embed’s Access control setting. When the token leaves it out, the Access control setting applies.
| Field | Type | Access control label | Default without either |
|---|---|---|---|
isEnableArchiveMetrics | boolean | Delete metrics | off |
isEnableManageMetrics | boolean | Manage metrics | off |
isEnableCreateDashboardView | boolean | Create boards | off |
isEnableMetricUpdation | boolean | Edit metrics | off |
isEnableCustomizeLayout | boolean | Customize dashboard layout | off |
isEnableUnderlyingData | boolean | View underlying data | off |
isEnableDownloadMetrics | boolean | Downloads | on |
isShowSideBar | boolean | Sidebar | on |
isShowDashboardName | boolean | Dashboard name | on |
isDisableMetricCreation | boolean | true turns off Create metrics | follows Create metrics |
A token cannot turn on Create metrics. Turn it on in the embed’s Access control.
Full example
{
"clientId": "acme-corp",
"dataAppName": "Customer Analytics",
"expiryTime": 3600000,
"params": {
"userIdentifier": "jane@acme.example",
"timezone": "America/New_York",
"allowedEmbeds": ["YOUR_DASHBOARD_ID"],
"dashboardAppFilters": [
{ "dashboardId": "YOUR_DASHBOARD_ID", "values": { "region": "East" } }
],
"tableAppFilters": [
{ "tableName": "public.orders", "columnName": "region", "values": ["East"] }
],
"hideDashboardFilters": ["Internal notes"]
},
"permissions": {
"isEnableUnderlyingData": true,
"isDisableMetricCreation": true
}
}The response is { "token": "<guest token>", "expireAt": "<ISO time>" }.
If something goes wrong
- 400
INVALID_REQUEST_BODY. A field is missing, has the wrong type or is not on this page. The message names it. - 400
INVALID_DATA_APP_NAME: “invalid data app name, data app name not found”.dataAppNamedoes not match a saved data app exactly. - 400
INVALID_REQUEST_BODY: “expiryTime must be a positive number of milliseconds from now.” Send a positive number. - 400
INVALID_TABLE_APP_FILTER. A table or column intableAppFiltersis not in the datamart.
See Error codes for the full list.