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

Embedding Setup

MCP Server

Framework Integration

Component Options

Authentication & Security

Filtering & Personalization

Customization

Events & Interactions

End-User Features

AI Chat Mode

Self-Hosted Deployment

Solution Patterns

Testing & Debugging

Migration & Legacy

Additional Resources

Quick start (simple use case):

Cloud Databrain Endpoint:

Self-hosted Databrain Endpoint:

Headers

Request Body

Request Body Examples:

Simple Request Body:

Request Body with App Level Metric Filter:

Request.json

Dashboard App Filters:

Request Body with Dashboard filters:

Datasource [Multi Datasource connection]:

Hide Dashboard Filters:

Allowed Embeds (optional)

Dashboard Permissions

User Identifier for Private & Publish Metrics

Timezone

Code Examples

HTTP Status Codes

Error Codes:

Embedding Setup

MCP Server

Framework Integration

Component Options

Authentication & Security

Filtering & Personalization

Customization

Events & Interactions

End-User Features

AI Chat Mode

Self-Hosted Deployment

Solution Patterns

Testing & Debugging

Migration & Legacy

Additional Resources

Documentation Index

​Quick start (simple use case):

​Cloud Databrain Endpoint:

​Self-hosted Databrain Endpoint:

​Headers

​Request Body

​Request Body Examples:

​Simple Request Body:

​Request Body with App Level Metric Filter:

Request.json

​Dashboard App Filters:

​Request Body with Dashboard filters:

​Datasource [Multi Datasource connection]:

​Hide Dashboard Filters:

​Allowed Embeds (optional)

​Dashboard Permissions

​User Identifier for Private & Publish Metrics

​Timezone

​Code Examples

​HTTP Status Codes

​Error Codes:

Quick start (simple use case):

Cloud Databrain Endpoint:

Self-hosted Databrain Endpoint:

Headers

Request Body

Request Body Examples:

Simple Request Body:

Request Body with App Level Metric Filter:

Dashboard App Filters:

Request Body with Dashboard filters:

Datasource [Multi Datasource connection]:

Hide Dashboard Filters:

Allowed Embeds (optional)

Dashboard Permissions

User Identifier for Private & Publish Metrics

Timezone

Code Examples

HTTP Status Codes

Error Codes: