Token

To obtain a guest token from DataBrain, utilize our REST API from your backend system. Each request will generate a unique guest token, ensuring security and flexibility.

Once you acquire the guest token, you can seamlessly pass it to your frontend application, where it can be integrated with the web component.

Create API key from Databrain's dashboard that should be passed in the headers in these requests.

Guest tokens are designed for frontend embedding. Never expose your API key in frontend code — always generate tokens from your backend.

Quick start (simple use case):

When you need a guest token that you want to use across dashboards and metrics, all you have to do is pass clientId, dataAppName. If expiryTime is not passed, the token will not expire.

Cloud Databrain Endpoint:

POST https://api.usedatabrain.com/api/v2/guest-token/create

Self-hosted Databrain Endpoint:

POST <SELF_HOSTED_URL>/api/v2/guest-token/create

Generating GUEST TOKEN for your Dashboard/Metric Component.

Headers

Name	Type	Description
Authorization*	String	Bearer API TOKEN
Content-Type*	String	Must be set to application/json for all requests

Request Body

Name	Type	Description
dataAppName*	String	Your Data App Name
clientId*	String	Client ID for whom this guest token is generated. ("clientId": "None" if no tenancy selected)
params	Object	Additional Params: allowedEmbeds, dashboardAppFilters, appFilters, hideDashboardFilters, userIdentifier, timezone
expiryTime	Number	In milliseconds. Common values: 3600000 (1 hour), 86400000 (24 hours), 604800000 (7 days)
datasourceName	String	Datasource name from Data Studio (important in case of multi-datasource embed setup)

// 200: OK
{
  "token": "..."
}

// 400: Bad Request
{
  "error": {
    "message": "invalid dashboard id",
    "code": "<ERROR_CODE>"
  }
}

// 401: Unauthorized
{
  "error": {
    "message": "API key is invalid or expired",
    "code": "AUTHENTICATION_ERR"
  }
}

Request Body Examples:

Simple Request Body:

{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname"
}

Request Body with App Level Metric Filter:

App filter
A metric level filter designed specifically for controlling access to individual metrics. Unlike general RLS settings, it restricts access without requiring end user input or control.

{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "params": {
    "appFilters": [{
      "metricId": "The id of the metric you want to have app filters",
      "values": {
        "paid_orders": true,
        "amount": 500,
        "country": ["USA", "CANADA"] || "USA", // based on filter variant (select or multi)
        {
          "sql": "SELECT \"name\" FROM \"public\".\"countries\" WHERE isEnabled=true",
          "columnName": "name"
        }
      }
    }]
  }
}

Request.json

Dashboard App Filters:

Request Body with Dashboard filters:

{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "params": {
    "dashboardAppFilters": [
      {
        "dashboardId": "dashboard-id",
        "values": {
          // single string
          "name": "Eric",

          // multi select
          "country": ["USA", "CANADA"] || "USA", // based on filter variant (select or multi)
          {
            "sql": "SELECT \"name\" FROM \"public\".\"countries\" WHERE isEnabled=true",
            "columnName": "name"
          },

          // date-picker
          "timePeriod": { "startDate": "2024-01-01", "endDate": "2024-3-23" },

          // range
          "price": { "min": 1000, "max": 5000 }
        },
        "isShowOnUrl": true // true/false
      }
    ]
  }
}

In the above code snippet, "name", "country", "timePeriod", and "price" are Dashboard App filters.
When you disable the isShowOnUrl, the filter will not be visible to end users as search params on URL.

Datasource [Multi Datasource connection]:

{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "datasourceName": "data source name"
}

datasourceName is available in app data studio tab.

Hide Dashboard Filters:

To hide dashboard filters in an embedded dashboard:

{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "params": {
    "hideDashboardFilters": ["filter 1", "filter 2"] // name of dashboard filters to hide
  }
}

Allowed Embeds (optional)

To restrict where a guest token can be used, pass an allowlist of embed IDs in params.allowedEmbeds. When set, the token will only be able to load embedded dashboards whose dashboardId is included in that list.

{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "params": {
    "allowedEmbeds": ["embed_abc123", "embed_def456"]
  }
}

Dashboard Permissions

To enable or disable few dashboard permissions from backend:

{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "permissions": {
    "isEnableArchiveMetrics": true, // true or false
    "isEnableManageMetrics": true, // true or false
    "isEnableCreateDashboardView": true, // true or false - allow creating custom dashboard views
    "isEnableMetricUpdation": true, // true or false
    "isEnableCustomizeLayout": true, // true or false
    "isEnableUnderlyingData": true, // true or false
    "isEnableDownloadMetrics": true, // true or false
    "isShowSideBar": true, // true or false - show the sidebar navigation
    "isShowDashboardName": true, // true or false - show the dashboard name in the interface
    "isDisableMetricCreation": false // true or false - disable metric creation for end users
  }
}

User Identifier for Private & Publish Metrics

Use userIdentifier inside the params object to uniquely identify the end-user in your embedded dashboard.
This enables features such as creating private metrics and publishing metrics directly from the embed view.

{
  "clientId": "id",
  "dataAppName": "dataappname",
  "params": {
    "userIdentifier": "unique-user-id-123"
  }
}

Note: userIdentifier should be a unique string representing the logged-in user in your system.

When set, any metrics created by this identifier can be managed (private or published) within the embedded environment.

isAllowPrivateMetricsByDefault should be enabled while creating the dashboard.

Timezone

Use timezone inside the params object to specify an IANA timezone string for timezone-aware queries and date/time formatting. When provided, SQL queries will be executed with this timezone setting, ensuring consistent date/time handling across different timezones.

Supported Datasources: Clickhouse, Trino, Redshift, CockroachDB, Postgres, MSSQL

Common timezone values: "UTC", "America/New_York", "America/Los_Angeles", "Europe/London", "Asia/Kolkata", "Australia/Sydney"

{
  "clientId": "id",
  "dataAppName": "dataappname",
  "params": {
    "timezone": "America/New_York"
  }
}

Code Examples

HTTP Status Codes

Status Code	Description
200	OK - Request succeeded
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to resource
404	Not Found - Resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error occurred

Rate Limiting: API requests are limited to prevent abuse. Implement exponential backoff for rate limited requests (429 status).

Error Codes:

Error Code	HTTP Status	Description
AUTHENTICATION_ERROR	401	Invalid or missing API key
INVALID_REQUEST_BODY	400	Missing or invalid parameters
CLIENT_ID_ERROR	400	Invalid clientId format or value
DATA_APP_ID_ERROR	404	Data app not found
WORKSPACE_ID_ERROR	404	Workspace not found or inaccessible
DASHBOARD_PARAM_ERROR	400	Invalid dashboard filter parameters
APP_FILTER_PARAM_ERROR	400	Invalid app filter configuration
RLS_SETTINGS_PARAM_ERROR	400	Invalid RLS settings
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_SERVER_ERROR	500	Server error
INVALID_PERMISSIONS	403	Invalid permission settings
EXPIRED_TOKEN	401	Token has expired