Production-Ready Embedding Guide

This guide walks you through everything you need to embed DataBrain dashboards in a production environment with proper authentication, security, and customization.

What You’ll Build

By the end of this guide, you’ll have:

✅ A secure backend endpoint that generates guest tokens
✅ A frontend application with embedded DataBrain dashboards
✅ Row-level security for multi-tenant access control (optional)
✅ Customized dashboard appearance matching your brand
✅ Production-ready authentication flow

Requirements: Basic knowledge of REST APIs, frontend frameworks, and environment variables Jump to any section:

Prerequisites
Architecture Overview
Step 1: Create Workspace & Dashboard
Step 2: Create Data App
Step 3: Backend Integration
Step 4: Frontend Integration
Step 5: Testing & Deployment
Next Steps

Prerequisites

Ensure you have the following before starting:

Requirement	Description	Link
DataBrain Account	Sign up for a free account	app.usedatabrain.com
Data Source	Connected database or data warehouse	Data Sources Guide
Backend Server	For secure token generation (Node.js, Python, Go, .NET, etc.)	-
Frontend App	React, Vue, Angular, or vanilla JS application	-

Architecture Overview

Flow Diagram:

Step 1: Create Workspace & Dashboard

1.1 Create a Workspace

Navigate to Workspaces

Go to the DataBrain platform and click “Create Workspace”

Configure Workspace

Enter workspace name
Select workspace type (standard or private)
Configure initial settings

Create Workspace Guide

Detailed workspace creation guide

1.2 Connect Data Source

Add Data Source

Click “Add Data Source” in your workspace

Select Database Type

Choose from 18+ supported databases

Enter Credentials

Provide connection details (host, port, credentials)

Test Connection

Verify the connection works

Configure Tenancy

Set up multi-tenancy if needed

Data Sources Guide

Connect your database

1.3 Create Dashboard

Create Dashboard

Click “New Dashboard” in your workspace

Add Metrics

Create charts, tables, and KPIs using the visual builder

Add Filters

Configure dashboard-level filters for interactivity

Customize Layout

Arrange metrics and adjust sizing

Save Dashboard

Save and note your dashboard ID

Create Dashboard Guide

Build your first dashboard

Step 1 Complete!Before moving to Step 2, verify you have:

Created a workspace in DataBrain
Successfully connected at least one data source
Built and saved a dashboard with metrics
Noted your dashboard ID for later use

Step 2: Create Data App

A Data App packages your dashboards for embedding with security and configuration.

2.1 Navigate to Data Apps

Go to Data → Data Apps in your workspace

2.2 Create New Data App

Click New Data App

Start creating a new Data App

Configure Basic Settings

{
  "name": "customer-analytics-app",
  "description": "Analytics for customer portal",
  "workspace": "your-workspace-name"
}

Select Dashboards

Choose which dashboards to include in this Data App

Configure Settings

Set default permissions
Configure multi-tenancy
Set token expiry defaults

Save and Get API Token

Copy your API token - you’ll need this for generating guest tokens

Store your API token securely! Never commit it to version control or expose it in frontend code. Use environment variables.

2.3 Find Your Dashboard ID

Open Data App

Navigate to your Data App

Find Dashboard Section

Look for the dashboards list

Copy Dashboard ID

Each dashboard has a unique ID (e.g., sales-dashboard-2024)

Finding Dashboard IDs

Detailed guide on locating IDs

Step 2 Complete!Before moving to Step 3, verify you have:

Created a Data App in your workspace
Added your dashboard(s) to the Data App
Copied and securely stored your API token
Have your Data App name ready (e.g., customer-analytics-app)

Step 3: Backend Integration

Set up your backend to generate guest tokens securely.

3.1 Store API Token

Add your DataBrain API token to environment variables:

DATABRAIN_API_TOKEN=dbn_live_abc123...
DATABRAIN_API_URL=https://api.usedatabrain.com
DATA_APP_NAME=customer-analytics-app

3.2 Implement Token Generation

Create an API endpoint to generate guest tokens:

// routes/databrain.js
const express = require('express');
const router = express.Router();

router.post('/guest-token', async (req, res) => {
  try {
    const { userId } = req.user; // From your auth middleware
    
    const response = await fetch(
      `${process.env.DATABRAIN_API_URL}/api/v2/guest-token/create`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.DATABRAIN_API_TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          clientId: userId,
          dataAppName: process.env.DATA_APP_NAME,
          expiryTime: 3600000 // 1 hour
        })
      }
    );
    
    const data = await response.json();
    
    if (!response.ok) {
      throw new Error(data.error?.message || 'Failed to generate token');
    }
    
    res.json({ token: data.token });
  } catch (error) {
    console.error('Token generation error:', error);
    res.status(500).json({ error: 'Failed to generate token' });
  }
});

module.exports = router;

Verify Token Generation

Test your endpoint to ensure tokens are being generated correctly:

curl -X POST http://localhost:3000/api/databrain/guest-token \
  -H "Authorization: Bearer your-app-auth-token" \
  -H "Content-Type: application/json"

# Expected Response:
# {
#   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
# }

Step 3 Complete!Before moving to Step 4, verify you have:

Environment variables configured with API token
Backend endpoint created for token generation
Successfully tested token generation (returns valid JWT)
Tokens are secured server-side (never exposed to frontend)

Step 4: Frontend Integration

4.1 Install Package

npm install @databrainhq/plugin

4.2 Create Dashboard Component

Basic Implementation (All Frameworks):

<dbn-dashboard 
  token={token}
  dashboard-id="sales-dashboard"
  enable-download-csv
  enable-download-all-metrics
/>

Step 4 Complete!Before moving to Step 5, verify you have:

Installed @databrainhq/plugin package
Created a dashboard component in your frontend
Dashboard successfully fetches token from your backend
Dashboard renders with data from DataBrain

Step 5: Testing & Deployment

5.1 Test Locally

Start Backend

Ensure your backend token endpoint is running

Start Frontend

Run your frontend development server

Verify Dashboard Loads

Check that the dashboard renders correctly

Test Interactions

Click on charts
Apply filters
Download CSV
Test responsive behavior

5.2 Environment Variables

Set up environment variables for each environment:

DATABRAIN_API_TOKEN=dbn_test_...
DATABRAIN_API_URL=https://api.usedatabrain.com
DATA_APP_NAME=my-app-dev

🎉 Congratulations! You’re Production-ReadyYour embedded analytics are now live! You’ve successfully:

Created DataBrain workspace and dashboards
Set up secure backend token generation
Integrated dashboard into your frontend
Deployed to production

What’s next? Explore multi-tenancy, SSO, and advanced customization below.

Next Steps

Multi-Tenancy

Implement row-level security

SSO Integration

Set up single sign-on

Advanced Customization

Deep dive into options

Solution Patterns

Common implementation patterns

Embedding Setup

Framework Integration

Component Options

Authentication & Security

Filtering & Personalization

Customization

Events & Interactions

End-User Features

AI Chat Mode

Self-Hosted Deployment

Solution Patterns

Testing & Debugging

Migration & Legacy

Additional Resources

​What You’ll Build

​Quick Navigation

​Prerequisites

​Architecture Overview

​Step 1: Create Workspace & Dashboard

​1.1 Create a Workspace

Create Workspace Guide

​1.2 Connect Data Source

Data Sources Guide

​1.3 Create Dashboard

Create Dashboard Guide

​Step 2: Create Data App

​2.1 Navigate to Data Apps

​2.2 Create New Data App

​2.3 Find Your Dashboard ID

Finding Dashboard IDs

​Step 3: Backend Integration

​3.1 Store API Token

​3.2 Implement Token Generation

​Verify Token Generation

​Step 4: Frontend Integration

​4.1 Install Package

​4.2 Create Dashboard Component

​Step 5: Testing & Deployment

​5.1 Test Locally

​5.2 Environment Variables

​Next Steps

Multi-Tenancy

SSO Integration

Advanced Customization

Solution Patterns

What You’ll Build

Quick Navigation

Prerequisites

Architecture Overview

Step 1: Create Workspace & Dashboard

1.1 Create a Workspace

1.2 Connect Data Source

1.3 Create Dashboard

Step 2: Create Data App

2.1 Navigate to Data Apps

2.2 Create New Data App

2.3 Find Your Dashboard ID

Step 3: Backend Integration

3.1 Store API Token

3.2 Implement Token Generation

Verify Token Generation

Step 4: Frontend Integration

4.1 Install Package

4.2 Create Dashboard Component

Step 5: Testing & Deployment

5.1 Test Locally

5.2 Environment Variables

Next Steps