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

# Getting Started

> How to Seamlessly Embed a DataBrain Dashboard

To embed a DataBrain dashboard into your application, we offer a straightforward approach using the DataBrain *npm* package. Simply install this package, and then bring it into your application to access a range of components. These components enable you to display full dashboards or specific metrics as needed.

<Card title="New: MCP Server" icon="wand-magic-sparkles" href="/developer-docs/mcp-server/overview">
  **Prefer using an AI assistant?** The Databrain MCP server lets you set up embeds, query data, and customize dashboards through natural language — in Cursor, Claude, Windsurf, or any MCP-compatible client. [Get started in 2 minutes →](/developer-docs/mcp-server/quickstart)
</Card>

## Multi-Tenancy Support

DataBrain supports embedding for different levels of tenancy based on how your client data is organized. Whether you separate data at the **table level** (rows identified by a client ID), **schema level**, **database level**, or across multiple datasources, DataBrain can handle your tenancy model.

Common tenancy models include:

* **Single Table Tenancy**: All client data in one table, separated by a `client_id` column
* **Multi-Level Tenancy**: Combining multiple layers (e.g., schema + table, database + schema)

Choose the right tenancy model based on your data architecture. Learn more about [choosing the right tenancy model](https://docs.usedatabrain.com/guides/onboarding-and-configuration/choosing-the-right-tenancy-model-for-your-data) and how to [configure tenants](https://docs.usedatabrain.com/guides/datasources/configure-tenants).

***

We've got you covered with a step-by-step guide here to help you integrate DataBrain dashboards into your user interface seamlessly.

## Step-by-Step Guide to Embed DataBrain Dashboard

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

  <Step title="Import the Plugin">
    ```js theme={"dark"}
    import '@databrainhq/plugin/web';
    ```
  </Step>

  <Step title="Use the Components in Your Application">
    For embedding a Dashboard

    ```html theme={"dark"}
    <dbn-dashboard token="token" dashboard-id="dashboardId" />
    ```

    or

    For embedding a Metric Card

    ```html theme={"dark"}
    <dbn-metric token="token" metric-id="metricId" />
    ```

    **Finding Your IDs**

    * **Dashboard ID**: In your Data App, navigate to **Embed Info** > **Add New Embed**. Select **workspace name**, choose embed type as **dashboard**, and select the dashboard. The **Embed ID** displayed is your dashboard ID. [See detailed guide here](https://docs.usedatabrain.com/developer-docs/helpers/dashboard-id).

    * **Metric ID**: In your Data App, go to **Embed Info** > **Add New Embed**. Provide the **workspace name**, select embed type as **metric**, choose the **dashboard** containing your metric, then select the metric. The **Embed ID** shown is your metric ID. [See detailed guide here](https://docs.usedatabrain.com/developer-docs/helpers/metric-id).

    **Token**

    The [`token`](https://docs.usedatabrain.com/developer-docs/token) should be a **guest token** generated from your backend using DataBrain's REST API. Each guest token is unique and ensures secure access control.

    **Generating a Guest Token:**

    Make a POST request from your backend to generate the guest token:

    **Cloud DataBrain:**

    ```http theme={"dark"}
    POST https://api.usedatabrain.com/api/v2/guest-token/create
    ```

    **Self-hosted DataBrain:**

    ```http theme={"dark"}
    POST <SELF_HOSTED_URL>/api/v2/guest-token/create
    ```

    **Request Headers:**

    ```json theme={"dark"}
    {
      "Authorization": "Bearer [API_TOKEN]"
    }
    ```

    **Minimum Request Body:**

    ```json theme={"dark"}
    {
      "clientId": "id",           // Use "None" if no tenancy selected
      "dataAppName": "dataappname"
    }
    ```

    The API will return a token that you pass to your frontend. The token can include additional parameters like `appFilters`, `dashboardAppFilters`, and `permissions` for fine-grained control. If `expiryTime` is not specified, the token won't expire.

    Learn more about [token generation and advanced options here](https://docs.usedatabrain.com/developer-docs/token).

    **Example for Embedding Dashboard:**

    Here is an example with a sample token and dashboardId that you can use in your frontend app to get started without a backend:

    ```html theme={"dark"}
    <dbn-dashboard token="3affda8b-7bd4-4a88-9687-105a94cfffab" dashboard-id="ex-demo" />
    ```
  </Step>
</Steps>

## Additional Resources and Customization

* **Customizing the Look and Feel**:
  * For further customizations related to the appearance of the embedded elements, [***refer here.***](https://docs.usedatabrain.com/developer-docs/helpers/options)
* **Understanding the Overall Architecture**:
  * For a comprehensive understanding of the overarching architecture and how embedding fits into it, [***refer here.***](https://docs.usedatabrain.com/developer-docs/embedding-setup/architecture-deep-dive)

With these steps, embedding DataBrain dashboards or metrics into your application can be done efficiently, offering a dynamic and insightful data visualization component to your users.