Token Management
Create a guest token
Your backend asks Databrain for a short-lived token that shows one customer only their own data.
A guest token lets one browser session show your embeds. Your backend creates it for each signed-in user. The browser gets only the guest token, never your API token.
Before you start
- You have an Embedded data app with at least one embed. Create a data app and embed
- You have that data app’s API token on your backend. Create an API token
- Your company has the Enterprise plan, or Databrain turned on Embedding for it.
Steps
-
Find the three values the request needs.
Field What to send clientIdYour customer company (the tenant), not a person. The value depends on your tenancy level. See the table below. dataAppNameThe data app’s name, exactly as it is saved. Case and spaces must match. params.userIdentifierOptional. The person who views the embed, for example your user ID or email. Databrain saves the metrics, dashboard views and reports this person makes under this value. The
clientIdvalue for each tenancy level:Tenancy level of the datasource clientIdisTable (one shared table, one column per customer) A value from the Primary key column of the Customer table, for example acme-corpfromclient_id.Database (one schema per customer) The customer’s schema name, for example acme_corp.Multi-database (one database per customer) The customer’s database name, for example acme_corp_db.No tenancy set Any string. It is required, but Databrain does not use it to filter rows. Every viewer sees every row. -
Send the request from your backend.
curl -X POST https://api.usedatabrain.com/api/v2/guest-token/create \ -H "Authorization: Bearer $DATABRAIN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "clientId": "acme-corp", "dataAppName": "Customer Portal", "params": { "userIdentifier": "user_8812" }, "expiryTime": 3600000 }'// Runs on your server. Never send DATABRAIN_API_TOKEN to the browser. app.get('/api/databrain-token', requireSignedInUser, async (req, res) => { const response = await fetch( 'https://api.usedatabrain.com/api/v2/guest-token/create', { method: 'POST', headers: { Authorization: `Bearer ${process.env.DATABRAIN_API_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ clientId: req.user.companyId, // the tenant, from your own session dataAppName: 'Customer Portal', params: { userIdentifier: req.user.id }, // the person expiryTime: 60 * 60 * 1000, // 1 hour, in milliseconds }), } ); const body = await response.json(); if (!response.ok) return res.status(response.status).json(body); res.json({ token: body.token, expireAt: body.expireAt }); });import os, requests def create_guest_token(company_id: str, user_id: str) -> dict: response = requests.post( "https://api.usedatabrain.com/api/v2/guest-token/create", headers={"Authorization": f"Bearer {os.environ['DATABRAIN_API_TOKEN']}"}, json={ "clientId": company_id, "dataAppName": "Customer Portal", "params": {"userIdentifier": user_id}, "expiryTime": 3600000, }, timeout=10, ) response.raise_for_status() return response.json() # {"token": "...", "expireAt": "..."} -
Read the response.
{ "token": "<guest token>", "expireAt": "2026-11-20T10:09:36.174Z" } -
Give
tokento the browser and set it on the element.<dbn-dashboard token="<guest token>" dashboard-id="revenue-overview"></dbn-dashboard>
The embed loads with only that customer’s rows. Next, embed your first dashboard.
Get the client ID from your session, never from the browser
Read clientId from your own signed-in session on the server. If the browser sends it, a user can change it and see another customer’s data. Use one token per customer company. Create a new token when the user switches company.
Token expiry
expiryTimeis the lifetime in milliseconds from now. It must be a positive number.- If you do not send
expiryTime, the token lasts 24 hours. - On the current self-serve plans, a token never lasts more than 24 hours. A longer request gets 24 hours.
expireAtin the response is the real expiry. Create a new token before that time.
More options in the body
Use these fields to filter data, hide parts of a dashboard and set permissions. See the guest token body reference for every field.
| Field | Use it to |
|---|---|
params.appFilters, params.dashboardAppFilters | Send filter values for one customer. Metric app filter, dashboard app filter |
params.rlsSettings, params.tableAppFilters | Restrict rows further. Multi-tenant access control |
params.allowedEmbeds | Limit the token to some dashboards of the data app. Send their dashboard IDs. |
params.hideDashboardMetrics, params.hideDashboardFilters | Hide cards or filters. |
params.timezone | Show dates in an IANA time zone, for example America/New_York. Guest token time zone |
permissions | Turn end-user actions on or off, for example isEnableUnderlyingData. |
datasourceName, datamartName | Pick one datasource or datamart when a workspace has more than one. |
If something goes wrong
Errors come back as { "error": { "code": "...", "message": "..." } }.
| Status and code | Cause | Fix |
|---|---|---|
403 entitlement_required | Embedding is not on your plan, or it is turned off for your company. The body also has capability: "embed", currentPlan and requiredPlan. | Move to the Enterprise plan, or ask Databrain to turn on Embedding. Embeds that already exist still render. |
400 INVALID_DATA_APP_NAME | No data app has this exact name. | Copy the name from Data Studio > Data Apps. Check case and spaces. |
400 AUTHENTICATION_ERROR | The API token belongs to a different data app. | Use an API token from the API tokens tab of this data app. |
400 CLIENT_ID_ERROR | clientId is not a customer of this data app. The hint says what a valid value is for your tenancy level. | Send a value from the client column, or the schema or database name. Run Sync Schema if the customer is new. |
503 CLIENT_ID_ERROR | Databrain could not check the client right now. details.retryable is true. | Try again. Check that the datasource is reachable. |
400 INVALID_REQUEST_BODY | A field is missing or has the wrong type, for example "clientId" is required or expiryTime must be a positive number of milliseconds from now. | Fix the field the message names. Unknown fields are refused too. |
400 APP_FILTER_PARAM_ERROR, RLS_SETTINGS_PARAM_ERROR | A filter name or metric ID in params does not exist. | Use the exact filter name and metric ID. |
400 DATASOURCE_NAME_ERROR, DATAMART_NAME_ERROR | No datasource or datamart has this name. | Check the name. |
503 entitlement_check_unavailable | Databrain could not read your plan. | Try again. |
The embed shows UNAUTHORIZED_ORIGIN when the page that shows it is not on the allowed domains list. Add your domain in Data Studio > Data Apps > (your app) > Domains.