User identity propagation

When embedding analytics with Toucan AI, it’s essential to ensure that each user’s identity and context are securely and accurately propagated from your application to the embedded analytics layer. This enables personalized experiences, fine-grained access control, and robust auditability.

---

What is User Identity Propagation?

User identity propagation is the process of passing the authenticated user’s identity and relevant attributes from your application to Toucan AI via the embed token. This ensures that:

• Each user only sees the data they are authorized to access (row-level security).

• Actions and queries can be attributed to the correct user for auditing and compliance.

• Personalized analytics and experiences are possible within embedded dashboards and assistants.

---

How It Works

1. User Authenticates in Your App: Your backend authenticates the user using your preferred method (SSO, OAuth, JWT, etc.).

2. Backend Generates a Token with User Identity: When generating the Toucan AI embed token, your backend includes user identity fields such as:

   • distinctId: A unique identifier for the user (required)

   • role: The user’s role in your application (e.g., explorer, maker, admin)

   • attributes: (Optional) Custom attributes for row-level security (e.g., department, region, customerId) Example payload:

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

3. Token Passed to Embedded Component: The signed token is sent to the frontend and provided to the embedded Toucan AI component.

4. Toucan AI Enforces Identity and Access: Toucan AI validates the token, applies row-level security, and ensures all actions are performed in the context of the correct user.

---

Why It Matters

• Security: Prevents unauthorized data access by ensuring every request is tied to a specific user and their permissions.

• Personalization: Enables user-specific dashboards, filters, and AI assistant responses.

• Auditability: All actions and queries can be traced back to the originating user for compliance and monitoring.

• Multi-Tenancy: Supports scenarios where different users or customers should only see their own data.

---

Best Practices

• Always use a unique, stable identifier for distinctId (e.g., your app’s user ID).

• Include all relevant attributes needed for row-level security or personalization.

• Never expose sensitive user information in the token unless required for access control.

• Generate and sign tokens server-side to prevent tampering.

• Regularly audit token usage and access logs for compliance.

---

Summary

User identity propagation is a core part of secure, personalized, and auditable embedded analytics with Toucan AI. By passing the right identity and context in your tokens, you ensure that every user gets the right data and experience—every time.