> 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/embed/permissions-and-row-level-security/how-to/apply-rls-to-your-database.md).

# Apply RLS to your database

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

### Goal

Establish a secure mapping between dynamic user attributes and dataset fields to filter data at query time.

***

### Prerequisites

* A [connected database](/build/data-connections/how-to/add-a-database.md) containing columns suitable for filtering (e.g., `region`, `team_id`, `department`).
* An [existing dashboard](/build/dashboards-and-layouts/how-to/create-a-dashboard-with-ai.md) or [chart](/build/charts/how-to/create-a-chart.md) to validate the filtering logic.
* A [valid API key](/embed/authentication/how-to/generate-an-api-key.md) to generate test tokens in the sandbox.

***

### Steps

#### 1. Verify dataset compatibility

* Navigate to the **Databases** tab and select the target **Database** and **Table**.
* Click **Preview** to confirm the presence of the column intended for filtering (e.g., a `location` column containing values like "Paris" or "Tokyo").

#### 2. Define custom token attributes

* Navigate to the **Settings** tab and select the **Embed & access** section.
* Locate the **Token Attributes** menu under **Custom Attributes**.
* Click **Add an attribute**.
* Input a factual **name** (e.g., `location`) and select the **data type** (e.g., `String`).
* Click **Save changes** to register the attribute for use in authentication tokens.

<figure><img src="/files/NDQc2pN1FwznNT5A7bju" alt="Custom attributes"><figcaption></figcaption></figure>

#### 3. Map attributes to database columns

* Return to the **Databases** section and select your **Database** and **Table**.
* Click the **Access rules** tab to configure security policies.
* Under the section "Then, for a row to be included...", use the rule builder to define your filter.
* In the **Select dataset field** dropdown, choose the column in your database you want to filter (e.g., `location_name`).
* Ensure the operator is set to **must be equal** to.
* In the **Select token attribute** dropdown, select the custom attribute created in Step 2 (e.g., `location`).

<figure><img src="/files/KfAG5jvLOCBGLy7q128o" alt="RLS settings"><figcaption></figcaption></figure>

#### 4. Enable and save RLS

* Click Save to activate the security policy.
* Verify that the RLS enabled blue tag appears next to the table name.
* You may repeat this mapping for additional tables that require the same security logic.

#### 5. Validate the RLS policy

* Within the table view, click **Preview with Token** in the top right corner.
* Enter a test value for your custom attribute (e.g., `Paris`) and click **Generate Preview**.
* Confirm that the displayed data rows are strictly limited to the value provided.

<figure><img src="/files/KH3plypehcA98WhUjDCn" alt="Preview RLS"><figcaption></figcaption></figure>

#### 6. Generate a test token and embed

* Navigate to **Settings > Embed & access** and scroll to the **Token Generation Sandbox**.
* Enter your **API Key** and assign a value to your custom attribute (e.g., `location` = `Paris`).
* Click **Generate Token**.
* Use this token in your embedded component (e.g., `<tc-dashboard auth-token="YOUR_TOKEN">`) to confirm the filtered view in your host application.

***

### Conclusion

The database now enforces Row-Level Security based on the identity context passed via authentication tokens. This ensures data isolation in multi-tenant environments without the need for multiple dashboards.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toucanai.cloud/embed/permissions-and-row-level-security/how-to/apply-rls-to-your-database.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.