Guest Token - Databrain

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

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

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

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

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, datasourceName) are optional for advanced use cases.

Advanced Features Available:

Dashboard & metric-level filtering (dashboardAppFilters, appFilters)
Embed allowlisting (params.allowedEmbeds)
Fine-grained permissions control (permissions object)
Private metrics for end users (userIdentifier)
Timezone-aware queries (params.timezone)
Multi-datasource support (datasourceName)
Conditional filter visibility (hideDashboardFilters, isShowOnUrl)
Token expiration management (expiryTime)

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.

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

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.

Use "None" as the value if no tenancy is configured for your workspace (e.g. "clientId": "None").

Show Best practices

Use your internal user ID
Keep it consistent across sessions
Alphanumeric characters recommended

dataAppName

string

required

The name of your data application. Must match an existing data app in your workspace and be alphanumeric.

Show Example values

"sales-dashboard"
"marketing-metrics"
"customer-analytics"

params

object

Additional parameters for token customization and filtering.

params.allowedEmbeds

array

Optional allowlist of specific embed IDs that this token can access.

If you provide allowedEmbeds, the guest token will only allow access to those specific embeds (by their embedId). All other embeds will be inaccessible with this token.
If this is omitted, there is no restriction on which embeds can be loaded by the token.
This is useful to restrict or enforce which dashboards or embedded analytics a guest can view, adding an extra layer of access control.

Show Example usage

{
  "clientId": "user-456",
  "dataAppName": "sales-dashboard",
  "params": {
    "allowedEmbeds": ["embed_abc123", "embed_def456"]
  }
}

params.appFilters

array

Application-level filters for controlling access to individual metrics. Unlike RLS settings, app filters restrict access without requiring end user input.

Metric App Filter

App filters are ideal for implementing metric-level access control that is invisible to end users.

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. Supports multiple data types:

Boolean: "paid_orders": true
Number: "amount": 500
String: "country": "USA"
Array (multi-select): "countries": ["USA", "CANADA"]
SQL Query: { "sql": "SELECT...", "columnName": "name" }

Show Example with multiple filter types

{
  "metricId": "metric_123",
  "values": {
    "paid_orders": true,
    "amount": 500,
    "country": ["USA", "CANADA"],
    "region": {
      "sql": "SELECT \"name\" FROM \"public\".\"regions\" WHERE isActive=true",
      "columnName": "name"
    }
  }
}

params.dashboardAppFilters

array

Dashboard-level filters that apply to all metrics on a dashboard. Supports multiple filter types for flexible data filtering.

Dashboard AppFilters

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. Supports various filter formats:

Single string: "name": "Eric"
Multi-select: "country": ["USA", "CANADA"]
Date range: "timePeriod": { "startDate": "2024-01-01", "endDate": "2024-03-23" }
Number range: "price": { "min": 1000, "max": 5000 }
SQL query: { "sql": "SELECT...", "columnName": "name" }

Show Complete example with all filter types

{
  "dashboardId": "dashboard_abc123",
  "values": {
    "name": "Eric",
    "country": ["USA", "CANADA"],
    "timePeriod": { 
      "startDate": "2024-01-01", 
      "endDate": "2024-03-23" 
    },
    "price": { "min": 1000, "max": 5000 },
    "region": {
      "sql": "SELECT \"name\" FROM \"public\".\"countries\" WHERE isEnabled=true",
      "columnName": "name"
    }
  },
  "isShowOnUrl": false
}

params.dashboardAppFilters.isShowOnUrl

boolean

default:"true"

Controls visibility of filter values in URL search parameters. When false, filters are applied but not visible to end users in the URL.

Set to false to hide sensitive filter criteria from end users while still applying the filtering logic.

params.hideDashboardFilters

array

Array of filter names to hide from the dashboard interface. Use this to conditionally hide specific filters based on user permissions or context.

Show Example usage

{
  "clientId": "user-456",
  "dataAppName": "sales-dashboard",
  "params": {
    "hideDashboardFilters": ["region_filter", "date_range", "status"]
  }
}

params.userIdentifier

string

Unique identifier for the end user in your system. Enables features like creating private metrics and publishing metrics directly from the embed view.

The isAllowPrivateMetricsByDefault setting must be enabled when creating the dashboard for this feature to work.

Show Use case example

When set, metrics created by this user identifier can be:

Saved as private (visible only to this user)
Published to share with other users
Managed independently per user

{
  "clientId": "client-123",
  "dataAppName": "analytics-app",
  "params": {
    "userIdentifier": "user_john_doe_789"
  }
}

params.timezone

string

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.

The timezone is used to set the database session timezone for SQL queries, ensuring that date/time operations are performed in the specified timezone.

Supported Datasources:

Clickhouse
Trino
Redshift
CockroachDB
Postgres
MSSQL

Want to implement timezone-aware dashboards end to end? See the full step-by-step guide: Timezone Handling in Guest Token.

Show Common timezone values

"UTC" - Coordinated Universal Time
"America/New_York" - Eastern Time (US)
"America/Los_Angeles" - Pacific Time (US)
"Europe/London" - Greenwich Mean Time / British Summer Time
"Asia/Kolkata" - Indian Standard Time
"Australia/Sydney" - Australian Eastern Time

{
  "clientId": "user-456",
  "dataAppName": "sales-dashboard",
  "params": {
    "timezone": "America/New_York"
  }
}

permissions

object

Permission settings for the embedded interface.

Permission Options

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.

permissions.isDisableMetricCreation

boolean

Disable metric creation in embedded dashboards. When set to true, end users cannot create new metrics.

Show Use case

Setting this to true disables only the metric creation feature for end users in the embedded interface.
If you want to allow metric creation again, you’ll need to update the embed configuration and set this option to false or remove it.
Overrides other metric creation permissions when enabled.

expiryTime

number

Optional. Token expiration time in milliseconds from now. If not provided, token never expires.

Show Common values

3600000 - 1 hour (3600 * 1000 ms)
86400000 - 24 hours
604800000 - 7 days

datasourceName

string

Optional. Datasource name for multi-datasource connection setups. Required when your data app uses multiple datasources.

The datasource name is available in the Data Studio tab of your dashboard. This parameter is only necessary if you have configured multiple datasources for your data app.

Show Multi-datasource example

{
  "clientId": "user-456",
  "dataAppName": "analytics-app",
  "datasourceName": "production_db_replica"
}

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.

HTTP Status Code Summary

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

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

Quick Start Guide

Getting Started

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

Next Steps

Embed a Pre-built Dashboard/Metric

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

Create Datasource

​Authentication

​Cloud Databrain Endpoint:

​Self-hosted Databrain Endpoint:

​Headers

​Request Body

​Response

​HTTP Status Code Summary

​Error Codes

​Quick Start Guide

Getting Started

​Next Steps

Embed a Pre-built Dashboard/Metric

Create Data App

How to Embed

API Token Helper

Authentication

Cloud Databrain Endpoint:

Self-hosted Databrain Endpoint:

Headers

Request Body

Response

HTTP Status Code Summary

Error Codes

Quick Start Guide

Next Steps