> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/getting-started/quick-start/embed-a-dashboard-1.md).

# Embed a self-service dashboard editor

{% hint style="info" %}
**Target Audience**: Non technical users & Developers
{% endhint %}

### Goal

Configure and embed a self-service dashboard editor into your application so end users can create their own dashboards from scratch.

Each dashboard is personal to the authenticated user and linked to the provided `auth-token`.

What this enables:

* End users create dashboards without leaving your app
* Dashboard ownership is scoped per user token

***

### Prerequisites

* A [Toucan AI account](/getting-started/quick-start/subscribe-to-toucan.md) and active organization.
* Credentials for a supported SQL database (e.g., PostgreSQL).
* A code editor or environment for testing HTML/web components (e.g., CodePen).

{% hint style="info" %}
This feature is currently configured through code integration (documentation snippet), not through the Toucan AI interface.
{% endhint %}

***

### Steps

#### 1: Create an API Key

* Navigate to your Account settings page by clicking on your profile icon in the bottom left corner, then go to the **API Keys** section.
* Create a new **API Key**. Copy it and store it securely.

This key will be used on your backend server to securely generate authentication tokens for your embedded application.

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2Fgit-blob-a61826644cc2472c248e659c1e2f408c4564998d%2Fsettings_api_keys.png?alt=media" alt="API Key"><figcaption></figcaption></figure>

{% hint style="danger" %}
**Security Alert**: This is a secret key. Never expose it in client-side code (HTML, JavaScript). Use it only on your secure backend server.
{% endhint %}

#### 2: Implement a user attribute model

(Optional) Define the attributes that will contextually personalize the experience for your users.

{% hint style="danger" %}
The user model will define user access to data (see "Define Row-Level Security (RLS)").
{% endhint %}

**Register User Attributes**

* Navigate to **Settings > Embed & access**.
* In the **Token Attributes** section, click **Add an attribute**.
* Define the traits you need (e.g., name: `region`, type: `String`). These must match the keys you will send in your user tokens.

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2Fgit-blob-a6f40f79b2da0017ea174ca94cf0f336229e17c9%2FToucanAI%20-%20Token%20Attributes.png?alt=media" alt="Token Attributes"><figcaption></figcaption></figure>

#### 3: Connect to a Database

* Navigate to the **Database** tab from the Home Page.
* Click **Add a Database** and select a connector.
* Input connection details including Host, Username, Password, and Database name.
* Click **Test Connection**, then click **Connect**.

{% hint style="info" %}
**Example:** Connect to your HR database containing employee data, including a **location** column with values like Tokyo, Paris, etc.
{% endhint %}

**How-To**: [Add a database](/build/data-connections/how-to/add-a-database.md)

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2Fgit-blob-6b5db74c0d08d51fca81eacb6c75819fd83da34c%2Fadd_a_database.png?alt=media" alt=""><figcaption></figcaption></figure>

#### 4: Complete Metadata Information

* Review existing table and column descriptions for accuracy.
* **(Recommended)**: Click **Analyze** from the database **More options** menu (⋮) to start an AI analysis run on selected schemas and tables.
  * The AI **proposes** descriptions, display names, and type casts — nothing is applied until you review and confirm.
  * Open **AI analyses** from the same menu to review proposals by kind (type casts, display names, descriptions).
  * Confirm each section to apply accepted proposals to your metadata.
* Ensure critical columns are described plainly to improve future AI prompt results.

**How-To**: [Analyze your database with AI](/build/analyze-your-database-with-ai/how-to/analyze-your-database-with-ai.md) · [Review AI analysis proposals](/build/analyze-your-database-with-ai/how-to/review-ai-analysis-proposals.md)

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2Fgit-blob-f833729d7ab558a7b7750d8360a22ed3ec068220%2Fai_analysis_runs_to_review.png?alt=media" alt="AI analyses waiting for review"><figcaption></figcaption></figure>

#### 5: Define Row-Level Security (RLS)

Secure your data so users only see what they are authorized to access.

1. Go to the **Database** tab and select a table.
2. In the **Access rules** section, map a **User Attribute** to a specific **dataset field** (a column of the table).
   * *Example*: Map the `user.region` attribute to the `sales_region` column.

This ensures that the AI automatically applies a filter (e.g., `WHERE sales_region = "North"`) based on the user attribute.

**How-To**: [Apply RLS to your database](https://github.com/ToucanToco/toucan-ai/blob/main/docs/permissions-and-row-level-security/how-to/apply-rls-to-your-database.md)

#### 6: **Behavior and user scope**

* The embedded editor lets users create dashboards from scratch.
* Each user only accesses their own dashboard workspace.
* A different `auth-token` results in a different personal dashboard context.

#### 7: Get an auth token

{% hint style="info" %}
You can customize the way the AI assistant will behave thanks to "AI context clues" within the token, where you can define the tone of voice, company context, etc.
{% endhint %}

For testing and configuration, you can generate a temporary token directly from the Toucan AI interface.

* Navigate to **Settings > Embed & access**.
* Scroll down to the **Token Generation Sandbox** section.
* Paste your **API Key**.
* Under **User Attributes**, configure the values for any custom attributes as well as the `aiContextClues` for this token.
* Click **Generate Token** and copy the resulting string.

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2Fgit-blob-342b8ff50db49fb7e3cb244c50d014b525f8d648%2Ftoken-generation-sandbox.jpg?alt=media" alt="Token generation sandbox"><figcaption></figcaption></figure>

{% hint style="info" %}
**Production Note**: For a live application, your backend server would generate these tokens dynamically via the API to securely authenticate your users and apply the correct security filters.
{% endhint %}

#### 8: Configure CORS and embed the dashboard editor

Before your embed can render, you must authorize the domain where it will be hosted.

* In the **Embed & access** settings, locate the **Authorized Origins** section.
* Add the URL of your application or development environment (e.g., `https://codepen.io`) and click Save.
* Copy the `<tc-self-service-dashboard/>` web component code:

```html
<script type="module" src="https://toucanai.cloud/embed/embed.js"></script>

<tc-self-service-dashboard
  server-url="https://toucanai.cloud/api"
  auth-token="your-auth-token"
  data-theme="light">
</tc-self-service-dashboard>
```

* Paste the code into your application's HTML.
* Replace the `Auth-Token` placeholder with your generated token.

Once the token has been copied into the web component, this is what it looks like (here on codepen.io, for example).

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2FPlKg0YKlof50uMOqhthv%2FCapture%20d%E2%80%99e%CC%81cran%202026-05-07%20a%CC%80%2015.40.43%20(2).png?alt=media&amp;token=63fa2def-e093-4166-8966-6de916f75ead" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The *AI chat + dashboard* option is available on the Grow pricing plan.
{% endhint %}

***

### Conclusion

You have successfully embedded a self-service dashboard editor.\
Your end users can now create and manage their own personal dashboards directly in your application, with each dashboard securely tied to the user’s authentication token.