User identity propagation

Target Audience: Developers

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

{
  "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.