# Embed a chat (/core/getting-started/quick-start/embed-a-chat)





















<CalloutContainer type="info">
  <CalloutDescription>
    **Target Audience**: Non technical users & Developers
  </CalloutDescription>
</CalloutContainer>

### Goal [#goal]

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

***

### Prerequisites [#prerequisites]

* A [Toucan AI account](/core/getting-started/quick-start/subscribe-to-toucan) 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 [#steps]

#### 1: Create an API Key [#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.

<img alt="API Key" src="__img0" />

<CalloutContainer type="error">
  <CalloutDescription>
    **Security Alert**: This is a secret key. Never expose it in client-side code (HTML, JavaScript). Use it only on your secure backend server.
  </CalloutDescription>
</CalloutContainer>

#### 2: Implement a user attribute model [#2-implement-a-user-attribute-model]

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

<CalloutContainer type="error">
  <CalloutDescription>
    The user model will define user access to data (see "Define Row-Level Security (RLS)").
  </CalloutDescription>
</CalloutContainer>

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

<img alt="Token Attributes" src="__img1" />

#### 3: Connect to a database [#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**.

<CalloutContainer type="info">
  <CalloutDescription>
    **Example:** Connect to your HR database containing employee data, including a **location** column with values like Tokyo, Paris, etc.
  </CalloutDescription>
</CalloutContainer>

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

<img src="__img2" />

#### 4: Complete Metadata Information [#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](/core/build/analyze-your-database-with-ai/how-to/analyze-your-database-with-ai) · [Review AI analysis proposals](/core/build/analyze-your-database-with-ai/how-to/review-ai-analysis-proposals)

<img alt="AI analyses waiting for review" src="__img3" />

#### 5: Define Row-Level Security (RLS) [#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 [#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` .

<img src="__img4" />

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.

<img src="__img5" />

*AI chat + dashboard embed (dashboard hidden)<br />Click the button at the top of the chat to show the dashboard.*

<img src="__img6" />

*AI chat + dashboard embed (dashboard visible)*

<CalloutContainer type="info">
  <CalloutDescription>
    The *AI chat + dashboard* option is available on the Grow pricing plan.
  </CalloutDescription>
</CalloutContainer>

#### 7: Get an auth token [#7-get-an-auth-token]

<CalloutContainer type="info">
  <CalloutDescription>
    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.
  </CalloutDescription>
</CalloutContainer>

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.

<img alt="Token generation sandbox" src="__img7" />

<CalloutContainer type="info">
  <CalloutDescription>
    **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.
  </CalloutDescription>
</CalloutContainer>

#### 8: Configure CORS and embed the chat [#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:

<img alt="Codepen embedded chat" src="__img8" />

***

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