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

# Dashboard embedding

> Embed 5X BI dashboards into external applications with secure authentication and row-level security

**Focus:** Learn how to embed 5X Business Intelligence dashboards into your applications with secure authentication, access control, and customizable user experiences.

## Dashboard embedding overview

Dashboard embedding enables you to integrate 5X Business Intelligence dashboards directly into your own applications via iframe. This provides a seamless way to bring data analytics into your native environment while maintaining security and access control.

### **Why embed dashboards?**

<CardGroup cols={2}>
  <Card title="Integrated experience" icon="puzzle-piece">
    **Seamless integration**

    Provide analytics within your application's native interface for a cohesive user experience.
  </Card>

  <Card title="Reduced context switching" icon="window-restore">
    **Stay in your app**

    Keep users in your application instead of redirecting them to external BI tools.
  </Card>

  <Card title="Customized branding" icon="palette">
    **Brand consistency**

    Maintain your application's look and feel while providing powerful analytics.
  </Card>

  <Card title="Flexible deployment" icon="rocket">
    **Easy deployment**

    Deploy analytics capabilities without building custom visualization components.
  </Card>
</CardGroup>

## Getting started with embedding

### **Two-step process**

Dashboard embedding is organized into two main phases:

**Phase 1: Preparation**

* Collect required 5X BI asset information
* Configure embedding settings and permissions
* Gather technical details for integration

**Phase 2: Deployment**

* Install the Superset Embedded SDK
* Implement guest token generation
* Embed dashboards in your application

### **Prerequisites**

**Required permissions:**

* **Admin/Developer role** access in your 5X workspace
* **Dashboard access** - Ability to view and configure dashboards
* **API access** - 5X API key for guest token generation

<Note>
  To obtain your 5X API key, please reach out to 5X Support at [support@5x.co](mailto:support@5x.co), contact us via Intercom, or reach out to your dedicated customer success manager.
</Note>

**Technical requirements:**

* **Backend service** - For secure guest token generation
* **Frontend application** - For SDK integration and iframe embedding
* **HTTPS** - Secure connection for embedded dashboards

## Phase 1: Preparation

### **Enable dashboard embedding**

1. **Access your dashboard**
   * Navigate to the dashboard you want to embed
   * Click the options menu (three dots) in the dashboard header
   * Select **"Embed dashboard"**

2. **Configure allowed domains**
   * Enter the domains where the dashboard will be embedded
   * Include development and production domains
   * Use full URLs with protocol (https\:// or http\://)

<Note>
  **Domain configuration tips:**

  * Wildcards are not supported - specify exact domains
  * Include all environments (dev, staging, prod)
  * Leave empty to allow embedding from any domain (not recommended for production)
</Note>

3. **Enable embedding**
   * Click **"Enable Embedding"**
   * Save the provided **Embedded Dashboard ID** for use in your application

### **Collect required information**

**Embedded Dashboard ID:**

* Unique identifier for the embedded dashboard
* Used with the Superset SDK to embed the dashboard
* Required for guest token generation

**Dashboard configuration:**

* **Dashboard settings** - Permissions, filters, and display options
* **Chart configurations** - Individual chart settings and interactions
* **Filter settings** - Global filters and their default values

## Phase 2: Deployment

### **Step 1: Create guest tokens (Backend)**

Guest tokens authenticate embedded users and define their data access permissions. They must be generated securely on your backend service.

**Guest token generation:**

```python theme={null}
import requests
import json

def generate_guest_token(api_key, user_info, dashboard_ids, rls_rules):
    """
    Generate a guest token for embedded dashboard access
    """
    payload = {
        "user": {
            "username": user_info["username"],
            "first_name": user_info["first_name"],
            "last_name": user_info["last_name"]
        },
        "dashboardIds": dashboard_ids,
        "rls": rls_rules
    }
    
    response = requests.post(
        "https://api-v1.5x.co/business-intelligence/v1/guest-token",
        data=json.dumps(payload),
        headers={"Authorization": f"Bearer {api_key}"}
    )
    
    return response.json()["data"]["guestToken"]
```

**Guest token parameters:**

* **user** (required) - User profile information
* **dashboardIds** (required) - List of dashboard IDs the user can access
* **rls** (required) - Row-level security rules for data access

### **Step 2: Supply guest tokens to frontend**

Create an endpoint in your application that generates and returns guest tokens:

```python theme={null}
from flask import Flask, request, jsonify
from flask_login import login_required, current_user

@app.route("/api/guest-token", methods=["GET"])
@login_required
def get_guest_token():
    """
    Generate guest token for authenticated user
    """
    # Define RLS rules based on user context
    rls_rules = [
        {"clause": f"user_id = '{current_user.id}'"},
        {"clause": f"organization_id = '{current_user.organization_id}'"}
    ]
    
    guest_token = generate_guest_token(
        api_key=os.getenv("5X_API_KEY"),
        user_info={
            "username": current_user.username,
            "first_name": current_user.first_name,
            "last_name": current_user.last_name
        },
        dashboard_ids=["1", "2"],  # Dashboard IDs user can access
        rls_rules=rls_rules
    )
    
    return jsonify({"guestToken": guest_token})
```

### **Step 3: Install the Superset Embedded SDK**

**From NPM:**

```bash theme={null}
npm install --save @superset-ui/embedded-sdk
```

**From CDN:**

```html theme={null}
<script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>
```

### **Step 4: Embed the dashboard**

**Using ES6 imports:**

```javascript theme={null}
import { embedDashboard } from "@superset-ui/embedded-sdk";

// Embed dashboard in your application
const dashboard = await embedDashboard({
    id: "abc123", // Embedded Dashboard ID from preparation phase
    supersetDomain: "https://your-workspace.5x.co",
    mountPoint: document.getElementById("dashboard-container"),
    fetchGuestToken: () => fetchGuestTokenFromBackend(),
    dashboardUiConfig: {
        hideTitle: true,
        filters: {
            expanded: true,
        },
        urlParams: {
            param_name: "value",
            other_param: "value",
        },
    },
});
```

**Using CDN:**

```html theme={null}
<script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>
<script>
    supersetEmbeddedSdk.embedDashboard({
        id: "abc123",
        supersetDomain: "https://your-workspace.5x.co",
        mountPoint: document.getElementById("dashboard-container"),
        fetchGuestToken: () => fetchGuestTokenFromBackend(),
        dashboardUiConfig: {
            hideTitle: true,
            filters: {
                expanded: true,
            },
        },
    });
</script>
```

## Security and access control

### **Row-level security (RLS)**

Row-level security provides fine-grained access control by applying additional WHERE clauses to data queries based on user context.

**RLS rule examples:**

```json theme={null}
{
    "rls": [
        {
            "clause": "user_id = 'grace_hopper'"
        },
        {
            "dataset": 16,
            "clause": "environment = 'production'"
        },
        {
            "dataset": 42,
            "clause": "state = 'published'"
        }
    ]
}
```

**RLS best practices:**

* **Dataset-specific rules** - Apply rules to specific datasets when possible
* **User context** - Use user information to filter data appropriately
* **Security validation** - Never insert untrusted input into RLS clauses
* **Testing** - Thoroughly test RLS rules to ensure proper data filtering

### **Domain restrictions**

**Configure allowed domains:**

* **Exact domain matching** - Specify exact domains (no wildcards)
* **Protocol inclusion** - Include https\:// or http\:// in domain specifications
* **Environment coverage** - Include all relevant environments (dev, staging, prod)
* **Security review** - Regularly review and update allowed domains

### **Authentication flow**

**Guest token lifecycle:**

* **1-hour expiration** - Guest tokens expire after 1 hour
* **Automatic refresh** - SDK automatically refreshes tokens
* **Secure generation** - Tokens generated only on trusted backend
* **No session persistence** - Embedded dashboards don't maintain 5X sessions

## Best practices

### **Security best practices**

<CardGroup cols={2}>
  <Card title="Secure token generation" icon="shield">
    **Backend only**

    Always generate guest tokens on your backend service, never expose API keys to frontend.
  </Card>

  <Card title="Principle of least privilege" icon="lock">
    **Minimal access**

    Grant only the minimum permissions necessary for each user's role and needs.
  </Card>

  <Card title="Regular security reviews" icon="clipboard-check">
    **Ongoing monitoring**

    Regularly review and audit access permissions and RLS rules.
  </Card>

  <Card title="Input validation" icon="shield-check">
    **Validate inputs**

    Always validate and sanitize user inputs before using them in RLS clauses.
  </Card>
</CardGroup>

## Troubleshooting

### **Common embedding issues**

<AccordionGroup>
  <Accordion icon="exclamation-triangle" title="Authentication failures">
    **Possible causes:**

    * Invalid or expired guest tokens
    * Incorrect API key configuration
    * Missing user information in token
    * Network connectivity issues

    **Solutions:**

    * Verify API key and token generation
    * Check user information completeness
    * Test network connectivity
    * Review token expiration handling
  </Accordion>

  <Accordion icon="eye-slash" title="Data not displaying">
    **Possible causes:**

    * RLS rules too restrictive
    * Missing dashboard permissions
    * Data source connection issues
    * Query errors or timeouts

    **Solutions:**

    * Review and adjust RLS rules
    * Verify dashboard access permissions
    * Check data source connections
    * Test queries independently
  </Accordion>

  <Accordion icon="window-maximize" title="Display issues">
    **Possible causes:**

    * Incorrect iframe sizing
    * CSS conflicts with parent application
    * Responsive design problems
    * Browser compatibility issues

    **Solutions:**

    * Adjust iframe dimensions and styling
    * Resolve CSS conflicts
    * Test responsive design
    * Check browser compatibility
  </Accordion>
</AccordionGroup>

***

Continue your Business Intelligence journey with these related guides.

<CardGroup cols={2}>
  <Card title="Dashboard Creation" icon="chart-line" href="/core-features/business-intelligence/dashboard-creation">
    **Create dashboards**

    Build dashboards that can be embedded in your applications.
  </Card>
</CardGroup>