Guest Token

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

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)
• Fine-grained permissions control (permissions object)
• Private metrics for end users (userIdentifier)
• 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.

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.

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

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

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