Create Embed Configuration

Create an embed configuration for an existing dashboard or metric with customizable access settings and permissions.

Create secure embed configurations for existing dashboards or metrics from your workspace. This endpoint allows you to share pre-built dashboards and metrics with external users by making them embeddable in your data app.

Endpoint Migration Notice: We’re transitioning to kebab-case endpoints. The new endpoint is /api/v2/data-app/embeds. The old endpoint /api/v2/dataApp/embeds will be deprecated soon. Please update your integrations to use the new endpoint format.

This endpoint embeds existing dashboards/metrics from your workspace. To create a new blank dashboard for multi-tenant scenarios, use the Create Dashboard Embed endpoint instead.

Endpoint Formats

New Endpoint (Recommended)

POST https://api.usedatabrain.com/api/v2/data-app/embeds

Use this endpoint for all new integrations. This is the recommended endpoint format.

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

dashboardId · string · required

Existing dashboard ID to embed. This dashboard must already exist in your workspace.

embedType · 'dashboard' | 'metric' · required

Type of embed configuration: dashboard or metric.

metricId · string

Metric ID to embed. Required if embedType is metric.

workspaceName · string · required

The name of the workspace where the embed configuration will be created.

accessSettings · object · required

Access control settings for the embedded view.

accessSettings.datamartName · string · required

The datamart name used in the embedded environment.

accessSettings.isAllowEmailReports · boolean · required

Allow sending email reports.

accessSettings.isAllowManageMetrics · boolean · required

Allow managing metrics.

accessSettings.isAllowCreateDashboardView · boolean · required

Allow creating dashboard views.

accessSettings.isAllowMetricCreation · boolean · required

Allow metric creation.

accessSettings.isAllowMetricDeletion · boolean · required

Allow metric deletion.

accessSettings.isAllowMetricLayoutChange · boolean · required

Allow metric layout changes.

accessSettings.isAllowMetricUpdate · boolean · required

Allow updating metrics.

accessSettings.isAllowUnderlyingData · boolean · required

Allow viewing underlying data.

accessSettings.metricCreationMode · 'DRAG_DROP' | 'CHAT' · required

Mode of metric creation (drag and drop or chat).

accessSettings.tableTenancySettings · array

Multi-tenant table access configuration (optional).

accessSettings.tableTenancySettings[].name · string

Table name for tenancy configuration.

accessSettings.tableTenancySettings[].clientColumn · string

Column name for client-level filtering.

Response

id · string

Unique identifier for the created embed configuration.

error · null | object

Error object if the request failed, otherwise null.

HTTP Status Code Summary

Status Code	Description
200	OK - Embed configuration created successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Dashboard or metric not found
500	Internal Server Error - Server error occurred

Possible Errors

Error Code	HTTP Status	Description
INVALID_WORKSPACE_NAME	404	Workspace not found
INVALID_DATA_APP_API_KEY	401	Invalid API key
INVALID_DASHBOARD_ID	404	Dashboard not found
INVALID_METRIC_ID	404	Metric not found
INTERNAL_SERVER_ERROR	500	Server error

Quick Start Guide

1. Get your API token

   For detailed instructions, see the API Token guide.

2. Create a dashboard in your workspace

   First, create and configure your dashboard in the DataBrain workspace with all the metrics and visualizations you want to embed.

3. Create embed configuration for dashboard

   Make a POST request to embed your existing dashboard:

   curl --request POST \
     --url https://api.usedatabrain.com/api/v2/data-app/embeds \
     --header 'Authorization: Bearer dbn_live_abc123...' \
     --header 'Content-Type: application/json' \
     --data '{
       "dashboardId": "existing-dashboard-id",
       "embedType": "dashboard",
       "workspaceName": "my-workspace",
       "accessSettings": {
         "datamartName": "my-datamart",
         "isAllowEmailReports": false,
         "isAllowManageMetrics": true,
         "isAllowCreateDashboardView": true,
         "isAllowMetricCreation": true,
         "isAllowMetricDeletion": false,
         "isAllowMetricLayoutChange": true,
         "isAllowMetricUpdate": true,
         "isAllowUnderlyingData": false,
         "metricCreationMode": "DRAG_DROP"
       }
     }'
   

4. (Optional) Embed a single metric

   To embed just one metric instead of the entire dashboard, use embedType: "metric":

   {
     "dashboardId": "existing-dashboard-id",
     "embedType": "metric",
     "metricId": "metric-123",
     "workspaceName": "my-workspace",
     // ... accessSettings
   }
   

5. Generate a guest token

   Use the embed ID to generate a guest token for your end users. See the Guest Token API for details.

6. Embed in your application

   Use the embed ID and guest token in your web component:

   <dbn-dashboard 
     token="guest-token-here" 
     dashboard-id="existing-dashboard-id" 
   />
   

Next Steps

Generate Guest Token

Create secure tokens for your embed configurations

Create New Dashboard

Create new blank dashboards for multi-tenant scenarios

Update Embed Config

Modify existing embed configurations

How to Embed

Learn how to integrate embeds in your application