> 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/authentication/user-identity-propagation.md).

# User identity propagation

{% hint style="info" %}
**Target Audience**: Developers
{% endhint %}

### TL;DR

Securely transmit user identity and contextual attributes from your application to Toucan AI via signed tokens to enable data isolation and personalized analytics.

***

### When to use this

Use this page to configure how your backend communicates a user's unique ID and access attributes (such as region or department) to Toucan AI for Row-Level Security (RLS) enforcement.

***

### Definition of identity propagation

User identity propagation is the process of transferring an authenticated user's identity and specific metadata from your host application to Toucan AI. This transfer occurs within the encrypted payload of the embed token.

#### **Core objectives**

* **Data Isolation**: Ensures Row-Level Security (RLS) restricts users to only the records they are authorized to view.
* **Compliance and Auditing**: Attributes every query and action to a specific user for monitoring and reporting purposes.
* **Contextual Experience**: Enables the dashboard or the AI assistant to provide personalized data filtered for the user's specific context.

***

### Technical workflow

The propagation follows a secure four-step sequence between your application and Toucan AI.

1. **Host Authentication**: Your backend verifies the user's identity using your internal system (e.g., SSO or OAuth).
2. **Token Payload Construction**: Your backend requests a Toucan AI token and includes a `user` object containing specific identity fields:
   * `distinctId` (Required): A unique, stable identifier for the user.
   * `role`: The user's specific role within Toucan AI (e.g., explorer, maker).
   * `attributes` (Optional): Custom key-value pairs (e.g., `customerId`, `region`) used to drive RLS logic.
3. **Frontend Transfer**: The backend delivers the signed token to the frontend, where it is injected into the `<tc-dashboard>` or `<tc-ai-assistant>` component.
4. **Verification and Enforcement**: Toucan AI validates the token signature and enforces data filters based on the provided attributes.

**Example token payload**

```json
{
  "user": {
    "distinctId": "user-123",
    "role": "explorer",
    "attributes": {
      "department": "finance",
      "region": "EMEA"
    }
  }
}
```

***

### Implementation best practices

* **Stable Identifiers**: Use your application's internal primary key as the `distinctId` to ensure consistent tracking.
* **Minimalist Attributes**: Only include the attributes strictly necessary for RLS or personalization to minimize token size.
* **Server-Side Security**: Tokens must be generated and signed on the server to prevent users from modifying their own attributes or permissions.
* **Data Privacy**: Do not include sensitive information in the token payload unless it is functionally required for access control.

***

### Summary table: propagation results

| Feature           | Outcome of propagation                                          |
| ----------------- | --------------------------------------------------------------- |
| **Multi-tenancy** | Users from different organizations only see their own data.     |
| **Security**      | Requests are tied to a specific identity and cannot be spoofed. |
| **Auditability**  | All actions can be traced to the `distinctId` provided.         |


---

# 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/authentication/user-identity-propagation.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.