Guest Token

Generate secure guest tokens for embedding DataBrain dashboards and metrics in your application.

POST /api/v2/guest-token/create

Authentication

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/guest-token/create \
  --header 'Authorization: Bearer dbn_live_...' \
  --header 'Content-Type: application/json'

200

{
  "token": "<string>",
  "error": {}
}

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

The request body is validated strictly — any field not documented on this page is rejected with INVALID_REQUEST_BODY. In particular, dataAppId, client_id, tenant_id, and permissions.dashboards are not valid fields.

Guest tokens are free. There is no charge, metering, or purchase involved in generating them.

Advanced Features Available:

• Dashboard & metric-level filtering (dashboardAppFilters, appFilters)
• Per-dashboard metric visibility (params.hideDashboardMetrics)
• 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)
• Multi-datamart support (datamartName)
• 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 IDs this token can load.

• Each entry must match the ID you pass to the embed component’s dashboardId attribute — embed IDs and dashboard IDs both resolve.
• If you provide allowedEmbeds, loading any ID not in the list fails with UNAUTHORIZED.
• 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-or-dashboard-id-1>", "<embed-or-dashboard-id-2>"]
  }
}

params.rlsSettings · array

Row-level security rules per metric. Each entry is { "metricId": string, "values": object }, where values maps RLS variable names to the values enforced for this token. Unlike dashboard filters, RLS values are enforced server-side and cannot be changed by the end user.

Show Example usage

{
  "clientId": "user-456",
  "dataAppName": "sales-dashboard",
  "params": {
    "rlsSettings": [
      { "metricId": "metric_123", "values": { "customer_id": "456", "region": "north-america" } }
    ]
  }
}

params.accessPermissions · object

End-user dashboard- and metric-filter controls. Supported fields include the filter permissions, optional column allowlists, and filter-name rename permissions.

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:

Keys in values can use either the filter label or internal filter name (case-insensitive).

• Boolean: "paid_orders": true
• Number: "amount": 500
• String: "country": "USA"
• Array (multi-select): "countries": ["USA", "CANADA"]
• Date preset shortcut: "order_date": "Last 30 days"
• 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:

Keys in values can use either the dashboard filter label or internal filter name (case-insensitive).

• Single string: "name": "Eric"
• Multi-select: "country": ["USA", "CANADA"]
• Date range: "timePeriod": { "startDate": "2024-01-01", "endDate": "2024-03-23" }
• Date preset shortcut: "timePeriod": "Last 30 days"
• 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.hideDashboardMetrics · array

Metrics to hide from specific embedded dashboards. Each item targets one dashboard and removes the selected metrics and their layout cards from that dashboard’s embed response.

params.hideDashboardMetrics[].dashboardId · string · required

External ID of the dashboard on which to hide the metrics. The dashboard must belong to the data app and workspace scope associated with the API token.

params.hideDashboardMetrics[].metricIds · array[string] · required

Public metric IDs to hide on the specified dashboard. Every metric must be present on that dashboard.

Show Example usage

{
  "clientId": "user-456",
  "dataAppName": "sales-dashboard",
  "params": {
    "hideDashboardMetrics": [
      {
        "dashboardId": "sales-overview",
        "metricIds": ["revenue-by-region", "gross-margin"]
      }
    ]
  }
}

This setting controls dashboard presentation for this guest token. It does not delete, archive, or change the metrics globally. Configurations for other dashboard IDs do not affect the current dashboard. If the same dashboard appears more than once, the backend combines the metric IDs from all matching entries.

params.accessPermissions · object

Optional advanced access controls for end-user dashboard filtering.

params.accessPermissions.isAllowEndUserDashboardFilter · boolean

Enables or disables end-user dashboard filter controls in embedded mode.

params.accessPermissions.dashboardFilterColumns · array

Optional allowlist for dashboard filterable columns. Each item must include tableName and columns.

params.accessPermissions.dashboardFilterColumns[].tableName · string · required

Fully qualified table name used in dashboard filters.

params.accessPermissions.dashboardFilterColumns[].columns · array[string] · required

Column names allowed for dashboard filter evaluation for the specified table.

params.accessPermissions.isAllowEndUserMetricFilter · boolean

Enables or disables end-user metric filter interactions in embedded mode.

params.accessPermissions.metricFilterColumns · array

Optional allowlist for columns that end users can use in metric filters. Each item must include tableName and columns.

params.accessPermissions.metricFilterColumns[].tableName · string · required

Fully qualified table name used in metric filters.

params.accessPermissions.metricFilterColumns[].columns · array[string] · required

Column names allowed for metric filter evaluation for the specified table.

params.accessPermissions.isAllowDashboardFilterNameChange · boolean

Enables or disables end-user renaming of dashboard filter labels in embedded mode.

params.accessPermissions.isAllowMetricFilterNameChange · boolean

Enables or disables end-user renaming of metric filter labels in embedded mode.

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, mint a new token with this option set to false or removed, and check the Data App’s Access Control settings and the component options (options.disableMetricCreation).
• 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

datamartName · string

Optional. Scope the token to a specific Datamart.

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

datamartName · string

Optional. Datamart name for multi-datamart connection setups. Use this when your data app can resolve multiple datamarts and you want to pin token execution to one datamart.

If both datasourceName and datamartName are omitted, Databrain resolves defaults from the data app context.

Show Multi-datamart example

{
  "clientId": "user-456",
  "dataAppName": "analytics-app",
  "datamartName": "sales-datamart"
}

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, 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 or a hideDashboardMetrics dashboard outside the API token’s data app/workspace scope
INVALID_METRIC_ID	400	A hideDashboardMetrics.metricIds value is not present on the specified dashboard
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

These are the mint-time errors from this endpoint. 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. Rate limiting surfaces as HTTP 429 with a Retry-After header (see Rate Limiting).

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