​
What is a Data App?

A Data App is a configured package of dashboards and metrics ready for embedding into your application. It acts as the bridge between your DataBrain workspace and your external application, managing authentication, permissions, and access control for embedded analytics.

​
Why Use Data Apps?

Embedding Ready

Pre-configured for easy integration into your app

Access Control

Manage who can see what with built-in security

API Token

Generate tokens for secure communication

Multi-Tenant

Support multiple customers with data isolation

​
Key Components

​
Dashboards & Metrics

Select which dashboards and metrics from your workspace should be available in the Data App.

​
API Token

Each Data App has a unique API token used to generate guest tokens for end users.

​
Embed Configuration

Settings that control how embedded components behave and what features are available.

​
Client Access

Define which clients (customers/users) can access the Data App and their data.

​
Creating a Data App

1

Navigate to Data Apps

Go to the Data section in your workspace and click “Data Apps”
2

Create New Data App

Click “New Data App” and provide a name
3

Select Dashboards

Choose which dashboards to include in the Data App
4

Configure Settings

Set up permissions, multi-tenancy, and other options
5

Get API Token

Copy your API token for use in generating guest tokens

Create a Data App

Detailed guide on creating Data Apps

​
Data App Settings

​
General Settings

  • Data App name and description
  • Associated workspace
  • Default datasource (for multi-datasource setups)

​
Embedding Configuration

  • Allowed domains for embedding
  • Default permissions for embedded views
  • Custom branding options

​
Security Settings

  • Token expiration policies
  • IP whitelisting
  • SSL/TLS requirements

​
API Token Management

The API token is used to authenticate requests from your backend to generate guest tokens.
Never expose your API token in frontend code. Always generate guest tokens from your backend server.

​
Token Best Practices

  • Store tokens securely (environment variables, secrets manager)
  • Rotate tokens periodically
  • Use different tokens for development and production
  • Monitor token usage

API Token Helper

Learn about API token management

​
Guest Token Generation

Guest tokens are temporary tokens that give end users access to your embedded dashboards.

​
How It Works

Token Flow: 
1. User logs into your app
   ↓
2. Your app requests guest token from your backend
   ↓
3. Your backend → DataBrain API (POST /guest-token/create)
   ↓
4. DataBrain API → Your backend (returns guest token)
   ↓
5. Your backend → Your app (returns guest token)
   ↓
6. Your app → Embedded component (passes token)
   ↓
7. Embedded component → DataBrain (loads dashboard)

​
Generate Guest Token

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/guest-token/create \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "user-123",
    "dataAppName": "my-data-app"
  }'

Guest Token API

Complete guest token API reference

​
Multi-Tenancy

Data Apps support multi-tenant architectures where each customer sees only their own data.

​
Row-Level Security (RLS)

Filter data automatically based on the client ID: 
{
  "clientId": "customer-456",
  "dataAppName": "analytics-app",
  "params": {
    "rlsSettings": [{
      "metricId": "sales-metric",
      "values": {
        "customer_id": "customer-456"
      }
    }]
  }
}

​
Client Isolation

Each client gets a unique view of the data with automatic filtering applied.

Multi-Tenant Access Control

Implement multi-tenancy in your app

​
Embedding Workflow

1

Create Data App

Set up your Data App in the DataBrain platform
2

Get API Token

Copy your API token from the Data App settings
3

Install NPM Package

npm install @databrainhq/plugin
4

Generate Guest Tokens

Create guest tokens from your backend for each user
5

Embed Components

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

​
Permissions & Features

Control what embedded users can do:

​
Metric Permissions

  • Archive metrics
  • Download metrics
  • View underlying data
  • Edit metrics
  • Create new metrics

​
Dashboard Permissions

  • Customize layout
  • Manage metrics
  • Create dashboard views
  • Download dashboards

​
UI Options

  • Show/hide sidebar
  • Show/hide dashboard name
  • Show/hide filters
  • Enable full-screen mode

Token Body Structure

Complete list of permission options

​
Use Cases

​
SaaS Analytics

Embed customer-specific dashboards in your SaaS product. Each customer sees only their data.

​
White-Label BI

Provide fully branded analytics to your clients under your brand.

​
Internal Tools

Build custom internal dashboards for your team with controlled access.

​
Partner Portals

Give partners access to relevant metrics and reports through embedded dashboards.

​
Advanced Configuration

​
Custom Filters

Pre-apply filters based on user context: 
{
  "params": {
    "dashboardAppFilters": [{
      "dashboardId": "sales-dashboard",
      "values": {
        "region": "North America",
        "date_range": {
          "startDate": "2024-01-01",
          "endDate": "2024-12-31"
        }
      }
    }]
  }
}

​
Dynamic Data Sources

Switch data sources based on the client: 
{
  "clientId": "customer-123",
  "dataAppName": "analytics-app",
  "datasourceName": "customer-123-db"
}

​
Monitoring & Analytics

Track usage of your Data App:
  • Active users
  • Most viewed dashboards
  • Query performance
  • Error rates
  • Token generation frequency

​
Best Practices

Always generate guest tokens server-side. Never expose API tokens in client code.
Use appropriate expiry times for guest tokens. Short-lived tokens are more secure.
Verify that RLS and data isolation work correctly for different client IDs.
Track query performance and optimize slow dashboards.
Maintain separate Data Apps for development, staging, and production.

​
Next Steps

Create Data App

Set up your first Data App

Embedding Guide

Learn how to embed dashboards

Guest Token API

API reference for token generation

Solution Patterns

Explore embedding patterns