Skip to Content

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

FieldTypeRequiredMeaning
clientIdstringYesThe tenant: your customer company, not a person. Its value depends on the tenancy level (see below).
dataAppNamestringYesThe data app’s saved name, exactly. Case and spaces count.
datamartNamestringNoName of the datamart to use.
datasourceNamestringNoName of the datasource to use.
expiryTimenumber or numeric stringNoToken life in milliseconds from now. Default 24 hours.
paramsobjectNoFilters, scope and the viewer’s identity.
permissionsobjectNoTurns embed features on or off for this token.

What to put in clientId

Tenancy levelclientId value
TableA value in the customer table’s primary key column, for example an org_id
DatabaseThe tenant’s schema name
Multi-databaseThe tenant’s database name
No tenancyStill required, but Databrain does not scope by it

See Tenancy model.

params

FieldTypeMeaning
userIdentifierstringThe 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.
timezonestringIANA time zone name, for example Asia/Kolkata. See Guest token timezone.
allowedEmbedsstring[]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.
hideDashboardFiltersstring[]Hides dashboard filters with these labels.
accessPermissionsobjectFilter permissions and auto client scope. See below.

tableAppFilters rules

  • tableName is schema.table, as the datamart shows it. No quotes or spaces.
  • columnName is a plain column name. No quotes or dots.
  • values holds 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

FieldTypeMeaning
isAllowEndUserDashboardFilterbooleanViewers can add dashboard filters
isAllowDashboardFilterNameChangebooleanViewers can rename dashboard filters
isAllowEndUserMetricFilterbooleanViewers can add metric filters
isAllowMetricFilterNameChangebooleanViewers can rename metric filters
dashboardFilterColumns{ tableName, columns[] }[]Columns viewers can use in dashboard filters
metricFilterColumns{ tableName, columns[] }[]Columns viewers can use in metric filters
isAllowAutoClientScopebooleanTable 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.

FieldTypeAccess control labelDefault without either
isEnableArchiveMetricsbooleanDelete metricsoff
isEnableManageMetricsbooleanManage metricsoff
isEnableCreateDashboardViewbooleanCreate boardsoff
isEnableMetricUpdationbooleanEdit metricsoff
isEnableCustomizeLayoutbooleanCustomize dashboard layoutoff
isEnableUnderlyingDatabooleanView underlying dataoff
isEnableDownloadMetricsbooleanDownloadson
isShowSideBarbooleanSidebaron
isShowDashboardNamebooleanDashboard nameon
isDisableMetricCreationbooleantrue turns off Create metricsfollows 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”. dataAppName does 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 in tableAppFilters is not in the datamart.

See Error codes for the full list.