Token

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/guest-token/create \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "user-456",
    "dataAppName": "sales-dashboard"
  }'

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/guest-token/create \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "user-456",
    "dataAppName": "sales-dashboard",
    "params": {
      "rlsSettings": [
        {
          "metricId": "metric_123",
          "values": {
            "customer_id": "456",
            "region": "north-america"
          }
        }
      ]
    },
    "expiryTime": 3600000
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/guest-token/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientId: 'user-456',
    dataAppName: 'sales-dashboard',
    params: {
      rlsSettings: [
        {
          metricId: 'metric_123',
          values: {
            customer_id: '456',
            region: 'north-america'
          }
        }
      ]
    },
    expiryTime: 3600000
  })
});

import requests

response = requests.post(
    'https://api.usedatabrain.com/api/v2/guest-token/create',
    headers={
        'Authorization': 'Bearer dbn_live_abc123...',
        'Content-Type': 'application/json'
    },
    json={
        'clientId': 'user-456',
        'dataAppName': 'sales-dashboard',
        'params': {
            'rlsSettings': [
                {
                    'metricId': 'metric_123',
                    'values': {
                        'customer_id': '456',
                        'region': 'north-america'
                    }
                }
            ]
        },
        'expiryTime': 3600000
    }
)

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.List;

HttpClient client = HttpClient.newHttpClient();
ObjectMapper mapper = new ObjectMapper();

Map<String, Object> requestBody = Map.of(
    "clientId", "user-456",
    "dataAppName", "sales-dashboard",
    "params", Map.of(
        "rlsSettings", List.of(
            Map.of(
                "metricId", "metric_123",
                "values", Map.of(
                    "customer_id", "456",
                    "region", "north-america"
                )
            )
        )
    ),
    "expiryTime", 3600000
);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.usedatabrain.com/api/v2/guest-token/create"))
    .header("Authorization", "Bearer dbn_live_abc123...")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(requestBody)))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

<?php
$curl = curl_init();

$data = [
    'clientId' => 'user-456',
    'dataAppName' => 'sales-dashboard',
    'params' => [
        'rlsSettings' => [
            [
                'metricId' => 'metric_123',
                'values' => [
                    'customer_id' => '456',
                    'region' => 'north-america'
                ]
            ]
        ]
    ],
    'expiryTime' => 3600000
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.usedatabrain.com/api/v2/guest-token/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer dbn_live_abc123...',
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
?>

require 'net/http'
require 'json'

uri = URI('https://api.usedatabrain.com/api/v2/guest-token/create')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer dbn_live_abc123...'
request['Content-Type'] = 'application/json'

request.body = {
  clientId: 'user-456',
  dataAppName: 'sales-dashboard',
  params: {
    rlsSettings: [
      {
        metricId: 'metric_123',
        values: {
          customer_id: '456',
          region: 'north-america'
        }
      }
    ]
  },
  expiryTime: 3600000
}.to_json

response = http.request(request)

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

type RLSValue struct {
    CustomerID string `json:"customer_id"`
    Region     string `json:"region"`
}

type RLSSetting struct {
    MetricID string   `json:"metricId"`
    Values   RLSValue `json:"values"`
}

type Params struct {
    RLSSettings []RLSSetting `json:"rlsSettings"`
}

type RequestBody struct {
    ClientID     string `json:"clientId"`
    DataAppName  string `json:"dataAppName"`
    Params       Params `json:"params"`
    ExpiryTime   int    `json:"expiryTime"`
}

func main() {
    requestBody := RequestBody{
        ClientID:    "user-456",
        DataAppName: "sales-dashboard",
        Params: Params{
            RLSSettings: []RLSSetting{
                {
                    MetricID: "metric_123",
                    Values: RLSValue{
                        CustomerID: "456",
                        Region:     "north-america",
                    },
                },
            },
        },
        ExpiryTime:   3600000,
    }

    jsonData, _ := json.Marshal(requestBody)
    
    req, _ := http.NewRequest("POST", "https://api.usedatabrain.com/api/v2/guest-token/create", bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class GuestTokenRequest
{
    [JsonProperty("clientId")]
    public string ClientId { get; set; }
    
    [JsonProperty("dataAppName")]
    public string DataAppName { get; set; }
    
    [JsonProperty("params")]
    public Params Params { get; set; }
    
    [JsonProperty("expiryTime")]
    public int ExpiryTime { get; set; }
}

public class Params
{
    [JsonProperty("rlsSettings")]
    public RLSSetting[] RlsSettings { get; set; }
}

public class RLSSetting
{
    [JsonProperty("metricId")]
    public string MetricId { get; set; }
    
    [JsonProperty("values")]
    public Values Values { get; set; }
}

public class Values
{
    [JsonProperty("customer_id")]
    public string CustomerId { get; set; }
    
    [JsonProperty("region")]
    public string Region { get; set; }
}

var client = new HttpClient();
var request = new GuestTokenRequest
{
    ClientId = "user-456",
    DataAppName = "sales-dashboard",
    Params = new Params
    {
        RlsSettings = new[]
        {
            new RLSSetting
            {
                MetricId = "metric_123",
                Values = new Values
                {
                    CustomerId = "456",
                    Region = "north-america"
                }
            }
        }
    },
    ExpiryTime = 3600000
};

var json = JsonConvert.SerializeObject(request);
var content = new StringContent(json, Encoding.UTF8, "application/json");

client.DefaultRequestHeaders.Add("Authorization", "Bearer dbn_live_abc123...");
var response = await client.PostAsync("https://api.usedatabrain.com/api/v2/guest-token/create", content);

This page is the guide. For the field-by-field API reference of this endpoint, see the canonical Guest Token API reference — if the two ever disagree, the API reference wins.

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: `rlsSettings`, `appFilters`, `dashboardAppFilters`, `hideDashboardFilters`, `allowedEmbeds`, `userIdentifier`, `timezone`, `accessPermissions`
permissions	Object	Dashboard permission toggles — see Dashboard Permissions below
expiryTime	Number	Duration in milliseconds from token creation. Common values: `3600000` (1 hour), `86400000` (24 hours), `604800000` (7 days). If omitted, the token never expires
datasourceName	String	Datasource name from Data Studio (important in case of multi-datasource embed setup)
datamartName	String	Optionally scope the token to a specific Datamart

The request body is validated strictly — any field not listed above is rejected with INVALID_REQUEST_BODY. In particular, dataAppId, tenant_id, client_id, and permissions.dashboards are not valid fields. Use clientId and dataAppName exactly as spelled here.

Guest tokens are free. There is no charge, metering, or purchase involved in generating them — mint as many as you need from your backend.

// 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_ERROR"
  }
}

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 which dashboards a guest token can load, pass an allowlist of IDs in params.allowedEmbeds. When set, the token can only load an embed whose ID (the value you pass to the component’s dashboard-id/dashboardId attribute — an embed ID or dashboard ID both work) is included in the list. Loading any other ID fails with UNAUTHORIZED.

{
  "clientId": "id", //"None" if no tenancy available
  "dataAppName": "dataappname",
  "params": {
    "allowedEmbeds": ["<embed-or-dashboard-id-1>", "<embed-or-dashboard-id-2>"]
  }
}

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, invalid, or unknown parameters (unrecognized fields are rejected)
`CLIENT_ID_ERROR`	400	Invalid clientId format or value
`INVALID_DATA_APP_NAME`	400	`dataAppName` doesn’t match any Data App (case-sensitive)
`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
`DATASOURCE_NAME_ERROR`	400	`datasourceName` doesn’t resolve
`DATAMART_NAME_ERROR`	400	`datamartName` doesn’t resolve
`INTERNAL_SERVER_ERROR`	500	Server error

At embed runtime (after minting), the distinct errors are INVALID_TOKEN (token not found in this deployment), TOKEN_EXPIRED, UNAUTHORIZED_ORIGIN, UNAUTHORIZED, and INVALID_ID — see the Error Codes Reference.

Security & Compliance

Token Body

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:

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