Skip to main content
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.

​
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:

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

​
Self-hosted Databrain:

POST <SELF_HOSTED_URL>/api/v2/guest-token/create
Generating GUEST TOKEN for your Dashboard/Metric Component.

​
Headers

NameTypeDescription
Authorization*StringBearer API TOKEN

​
Request Body

NameTypeDescription
dataAppName*StringYour Data App Name
clientId*StringClient ID for whom this guest token is generated. ("clientId": "None" if no tenancy selected)
paramsObjectAdditional Params: dashboard, appFilters
expiryTimeNumberIn milliseconds
datasourceNameStringDatasource 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
  }
}

​
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
    "isEnableMetricUpdation": true, // true or false
    "isEnableCustomizeLayout": true, // true or false
    "isEnableUnderlyingData": true, // true or false
    "isEnableDownloadMetrics": true // true or false
  }
}

​
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.

​
Error Codes:

  • 'AUTHENTICATION_ERROR'
  • 'INVALID_REQUEST_BODY'
  • 'CLIENT_ID_ERROR'
  • 'WORKSPACE_ID_ERROR'
  • 'DASHBOARD_PARAM_ERROR'
  • 'APP_FILTER_PARAM_ERROR'
  • 'RLS_SETTINGS_PARAM_ERROR'
  • 'INTERNAL_SERVER_ERROR'