> 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/authentication-models.md).

# Authentication models

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

### TL;DR

Toucan AI utilizes server-side token generation to authorize user access and enforce data isolation for embedded components.

***

### When to use this

Use this page to understand the technical workflow for securing embedded dashboards and the AI assistant, ensuring each user only accesses authorized data.

***

### Purpose of Authentication

Authentication establishes a secure link between the host application and Toucan AI. It serves two primary functions:

* **Access Control**: Verifies that a user is authorized to view specific dashboards, charts, or the AI assistant.
* **Data Scoping**: Enables Row-Level Security (RLS) and multi-tenant isolation by passing user context from the host application to Toucan AI.

***

### Token-Based Authentication

This is the standard model for production environments. It relies on a secure handshake between your backend and the Toucan AI API.

**Technical Workflow**

1. **Identity Verification**: Your application authenticates the user through your existing system (e.g., SSO, OAuth, or JWT).
2. **Token Generation**: Your backend requests a signed session token from Toucan AI using a secure API key. This token encodes the user identity and custom attributes like `organization_id` or `region`.
3. **Frontend Delivery**: The backend passes this token to the frontend, where it is injected into the `<tc-dashboard>` or `<tc-ai-assistant>` web component.
4. **Validation**: Toucan AI validates the token signature and enforces the associated RLS rules during data execution.

**Use Case Suitability**

* **Multi-tenant SaaS**: Essential for isolating customer data within shared database schemas.
* **Production Environments**: Required for any scenario where API keys must be protected from client-side exposure.
* **Dynamic Scoping**: Best for applications where data access changes frequently based on user roles or departments.

<figure><img src="https://4270790459-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl0BD9cL6TJjTGV95tGak%2Fuploads%2Fgit-blob-bae7abe6f10832001b065128dd4ddea28e42e04a%2Fauthentication_flow.png?alt=media" alt="Authentication Flow"><figcaption></figcaption></figure>

***

### Security Best Practices

* **Server-Side Execution**: Always generate and sign tokens on your backend; never expose API keys or signing secrets in client-side code.
* **Token Expiration**: Implement short-lived tokens to minimize the impact of potential session compromise.
* **Credential Rotation**: Regularly rotate API keys within the Toucan AI settings to maintain platform security.
* **Minimalist Attributes**: Include only the specific attributes required for access control and RLS to maintain efficient token payloads.