Skip to main content
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"
  }'

{
  "token": "3affda8b-7bd4-4a88-9687-105a94cfffab"
}
POST
/
api
/
v2
/
guest-token
/
create
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"
  }'

{
  "token": "3affda8b-7bd4-4a88-9687-105a94cfffab"
}
Generate guest tokens from DataBrain backend for embedding. Each request generates a unique guest token, ensuring security and flexibility for your embedded analytics.
Guest tokens are designed for frontend embedding. Never expose your API key in frontend code - always generate tokens from your backend.
Simple Usage: Only clientId and dataAppName are required. All other parameters (params, permissions, expiryTime) are optional for advanced use cases.

​
Authentication

All API requests must include your API key in the Authorization header. Get your API token when creating a data app - see our data app creation guide for details. Finding your API token: For detailed instructions, see the API Token guide.

​
Headers

​
Authorization
string
required
Bearer token for API authentication. Use your API key from the data app.
Authorization: Bearer dbn_live_abc123...
​
Content-Type
string
required
Must be set to application/json for all requests.
Content-Type: application/json

​
Request Body

​
clientId
string
required
Unique identifier for the end user. This should be your user’s ID from your system. Used for row-level security and access control.
​
dataAppName
string
required
The name of your data application. Must match an existing data app in your workspace and be alphanumeric.
​
params
object
Additional parameters for token customization and filtering.
​
params.rlsSettings
array
Row-level security settings for metric filtering.
​
params.rlsSettings.metricId
string
The metric ID to apply RLS settings to. Required if rlsSettings is provided.
​
params.rlsSettings.values
object
Key-value pairs for row-level filtering. Required if rlsSettings is provided.
Example
{
  "customer_id": "123",
  "region": "north-america"
}
​
params.appFilters
array
Application-level filters for metrics.
​
params.appFilters.metricId
string
The metric ID to apply filters to. Required if appFilters is provided.
​
params.appFilters.values
object
Filter values to apply to the metric. Required if appFilters is provided.
​
params.dashboardAppFilters
array
Dashboard-level filters that apply to all metrics on a dashboard.
​
params.dashboardAppFilters.dashboardId
string
The dashboard ID to apply filters to. Required if dashboardAppFilters is provided.
​
params.dashboardAppFilters.values
object
Filter values to apply to the dashboard. Required if dashboardAppFilters is provided.
​
params.dashboardAppFilters.isShowOnUrl
boolean
Whether to show these filters in the URL parameters.
​
params.hideDashboardFilters
array
Array of filter names to hide from the dashboard interface.
Example
["region_filter", "date_range"]
​
permissions
object
Permission settings for the embedded interface.
​
permissions.isEnableArchiveMetrics
boolean
Allow archiving metrics.
​
permissions.isEnableManageMetrics
boolean
Allow managing metrics (view, edit, organize).
​
permissions.isEnableCreateDashboardView
boolean
Allow creating custom dashboard views.
​
permissions.isEnableMetricUpdation
boolean
Allow updating metric configurations.
​
permissions.isEnableCustomizeLayout
boolean
Allow customizing dashboard layout.
​
permissions.isEnableUnderlyingData
boolean
Allow viewing underlying data behind charts.
​
permissions.isEnableDownloadMetrics
boolean
Allow downloading metric data.
​
permissions.isShowSideBar
boolean
Show the sidebar navigation.
​
permissions.isShowDashboardName
boolean
Show the dashboard name in the interface.
​
expiryTime
number
Token expiration time in milliseconds from now. If not provided, token never expires.

​
Response

​
token
string
UUID token for authentication. Pass this to your frontend component for embedding.
​
error
null | object
Error object if the request failed, otherwise null for successful requests.

​
Error Codes

​
AUTHENTICATION_ERROR
string
Invalid API key - Check your API key in dashboard settings
​
INVALID_REQUEST_BODY
string
Missing or invalid parameters - Verify all required fields are provided with correct types
​
DATA_APP_ID_ERROR
string
Invalid data app - The specified dataAppName doesn’t exist or you don’t have access
​
INTERNAL_SERVER_ERROR
string
Server error - Contact support if error persists

​
HTTP Status Code Summary

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

​
Possible Errors

Error CodeHTTP StatusDescriptionSolution
AUTHENTICATION_ERROR401Invalid or missing API keyVerify your API key is correct and included in Authorization header
INVALID_REQUEST_BODY400Missing or invalid parametersCheck all required fields are provided with correct data types
DATA_APP_ID_ERROR404Data app not foundVerify the dataAppName exists and you have access
RATE_LIMIT_EXCEEDED429Too many requestsImplement exponential backoff and retry logic
INTERNAL_SERVER_ERROR500Server errorContact support if error persists
INVALID_CLIENT_ID400Invalid clientId formatUse alphanumeric characters for clientId
EXPIRED_TOKEN401Token has expiredGenerate a new token
INVALID_PERMISSIONS403Invalid permission settingsCheck permission object structure

​
Quick Start Guide

1

Get your API token

For detailed instructions, see the API Token guide.
2

Create a guest token

Make a POST request to generate a token for your user:
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"
  }'
3

Use the token in your frontend

Pass the returned token to your DataBrain component:
<dbn-dashboard token="3affda8b-7bd4-4a88-9687-105a94cfffab" dashboard-id="your-dashboard-id" />
Rate Limiting: API requests are limited to prevent abuse. Implement exponential backoff for rate limited requests (429 status).

​
Next Steps

Create Embed Configuration

Create embed configurations for your data apps

Create Data App

Create data apps and get your API tokens

How to Embed

Learn how to embed dashboards in your app

API Token Helper

Learn more about API token management
⌘I