> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Apps

> Package dashboards and metrics for embedding in your application

## 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?

<CardGroup cols={2}>
  <Card title="Embedding Ready" icon="code">
    Pre-configured for easy integration into your app
  </Card>

  <Card title="Access Control" icon="shield">
    Manage who can see what with built-in security
  </Card>

  <Card title="API Token" icon="key">
    Generate tokens for secure communication
  </Card>

  <Card title="Multi-Tenant" icon="users">
    Support multiple customers with data isolation
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="Navigate to Data Apps">
    Go to the Data section in your workspace and click "Data Apps"
  </Step>

  <Step title="Create New Data App">
    Click "New Data App" and provide a name
  </Step>

  <Step title="Select Dashboards">
    Choose which dashboards to include in the Data App
  </Step>

  <Step title="Configure Settings">
    Set up permissions, multi-tenancy, and other options
  </Step>

  <Step title="Get API Token">
    Copy your API token for use in generating guest tokens
  </Step>
</Steps>

<Card title="Create a Data App" icon="plus" href="/guides/datasources/create-a-data-app">
  Detailed guide on creating Data Apps
</Card>

## Data App Settings

Data Apps share the same embed settings as workspace-level embed settings. Access these from the Data App settings sidebar:

### Embed Settings

* **API Token**: Generate and manage API tokens for the Data App
* **Theme Settings**: Configure UI theming for embedded dashboards
* **Email Settings**: Configure scheduled email report settings
* **Preview Settings**: Configure demo/preview configuration
* **Whitelist Domains**: Manage allowed domains for embedding

### Integration Settings

For specific Data App types (e.g., MS Teams, Slack), additional integration-specific settings are available:

* **MS Teams**: Configure Teams-specific integration fields
* **Slack**: Connect Slack workspace and select channels

## API Token Management

The API token is used to authenticate requests from your backend to generate guest tokens.

<Warning>
  **Never expose your API token in frontend code.** Always generate guest tokens from your backend server.
</Warning>

### Token Best Practices

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

<Card title="API Token Helper" icon="key" href="/developer-docs/helpers/api-token">
  Learn about API token management
</Card>

## 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

```bash theme={"dark"}
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"
  }'
```

<Card title="Guest Token API" icon="key" href="/developer-docs/helpers/api-reference/token">
  Complete guest token API reference
</Card>

## 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:

```json theme={"dark"}
{
  "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.

<Card title="Multi-Tenant Access Control" icon="users" href="/developer-docs/multi-tenant-access-control">
  Implement multi-tenancy in your app
</Card>

## Embedding Workflow

<Steps>
  <Step title="Create Data App">
    Set up your Data App in the DataBrain platform
  </Step>

  <Step title="Get API Token">
    Copy your API token from the Data App settings
  </Step>

  <Step title="Install NPM Package">
    ```bash theme={"dark"}
    npm install @databrainhq/plugin
    ```
  </Step>

  <Step title="Generate Guest Tokens">
    Create guest tokens from your backend for each user
  </Step>

  <Step title="Embed Components">
    ```html theme={"dark"}
    <dbn-dashboard 
      token="guest-token" 
      dashboard-id="dashboard-id" 
    />
    ```
  </Step>
</Steps>

## 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

<Card title="Token Body Structure" icon="list" href="/developer-docs/helpers/token-body">
  Complete list of permission options
</Card>

## 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:

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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

<AccordionGroup>
  <Accordion title="Secure Token Generation" icon="shield">
    Always generate guest tokens server-side. Never expose API tokens in client code.
  </Accordion>

  <Accordion title="Set Token Expiry" icon="clock">
    Use appropriate expiry times for guest tokens. Short-lived tokens are more secure.
  </Accordion>

  <Accordion title="Test with Different Clients" icon="users">
    Verify that RLS and data isolation work correctly for different client IDs.
  </Accordion>

  <Accordion title="Monitor Performance" icon="gauge">
    Track query performance and optimize slow dashboards.
  </Accordion>

  <Accordion title="Version Your Apps" icon="code-branch">
    Maintain separate Data Apps for development, staging, and production.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Data App" icon="plus" href="/guides/datasources/create-a-data-app">
    Set up your first Data App
  </Card>

  <Card title="Embedding Guide" icon="code" href="/developer-docs/how-to-embed">
    Learn how to embed dashboards
  </Card>

  <Card title="Guest Token API" icon="key" href="/developer-docs/helpers/api-reference/token">
    API reference for token generation
  </Card>

  <Card title="Solution Patterns" icon="lightbulb" href="/developer-docs/solutions-alchemy/dashboard-for-multiple-clients">
    Explore embedding patterns
  </Card>
</CardGroup>