> 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-chat.md).

# Embed a chat

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

### Goal

Configure and embed a self-service chat experience into your application, allowing users to explore data using natural language.

***

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

***

### 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: Configure a chat

In the menu, go to the [chat page](https://toucanai.cloud/chat), and click "Embed" in the top right corner, then copy the snippet provided.

When configuring your embed, you can choose between two experiences:

* **AI chat only:** embed only the conversational interface.
* **AI chat + dashboard**: embed the chat with a personal dashboard for each user. The dashboard is linked to the provided `auth-token` .

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2FOInPpJhanRfjdPzN7Sls%2FCapture%20d%E2%80%99e%CC%81cran%202026-05-06%20a%CC%80%2015.40.01.png?alt=media&amp;token=87c54305-9b9f-4c4f-bb1c-ec37a7fdd570" alt=""><figcaption></figcaption></figure>

As you can see, there is a placeholder for the auth token in this snippet (`auth-token="your-auth-token"`).

You can also personalize the chat experience with attributes such as:

* `welcome-message`: the first message displayed to users when the chat opens.
* `prompt-placeholder`: the placeholder text shown in the input field before the user starts typing.
* `data-theme`: optional setting to switch between `light` and `dark`.

Below is an example of what an embedded chat looks like when displayed with its associated dashboard.

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2FsJOGK9coCE7BsZx3dP6O%2FCapture%20d%E2%80%99e%CC%81cran%202026-05-06%20a%CC%80%2015.57.51.png?alt=media&amp;token=814dd21d-562c-4c58-9957-dbce4b924eee" alt=""><figcaption><p>AI chat + dashboard embed (dashboard hidden)<br>Click the button at the top of the chat to show the dashboard.</p></figcaption></figure>

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2FkOyGuGeG8oaNe71JeVTV%2FCapture%20d%E2%80%99e%CC%81cran%202026-05-06%20a%CC%80%2015.57.06.png?alt=media&amp;token=5364bd25-9e75-4753-b64e-720de47d7038" alt=""><figcaption><p>AI chat + dashboard embed (dashboard visible)</p></figcaption></figure>

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

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

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.
* Go to your application's code and paste the snippet you retrieved in Step 6.
* Replace `your-auth-token` with the token you generated in the previous step.

Example result in codepen:

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2Fgit-blob-a3f82fdfca42aa952a9eaef5da8ec28c3005530b%2Fcodepen-embedded-chat.jpg?alt=media" alt="Codepen embedded chat"><figcaption></figcaption></figure>

***

### Conclusion

You have successfully configured and embedded a self-service chat. Your users can now ask questions and receive data-driven answers secured by your RLS and CLS policies.