> 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/embedding-overview/security-boundaries.md).

# Security boundaries

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

### TL;DR

Toucan AI utilizes a multi-layered security model combining server-side token generation, row-level security (RLS), and origin restrictions to protect embedded data.

***

### When to use this

Use this page to understand the division of security responsibilities between your application and Toucan AI, and to implement best practices for multi-tenant data isolation.

***

### Key Security Principles

Toucan AI follows a "security-by-design" approach to ensure that data access remains controlled and compliant.

* **Separation of Concerns**: Your application manages user identity and authentication. Toucan AI processes data and rendering requests only when presented with a valid, authorized token.
* **Token-Based Access Control**: Every embedded component requires a signed token that defines the user or tenant identity, object-level access permissions, and token expiration.
* **Row-Level Security (RLS)**: Fine-grained access is enforced by mapping attributes within the authentication token (e.g., `user_id`, `region`) to specific database columns.
* **API Key Management**: API keys must remain on the server side to authorize token requests. Exposing keys in client-side code is a security risk.
* **Origin Restrictions**: Security settings allow you to specify authorized domains (origins) where Toucan AI components are permitted to render.
* **Data Residency**: Deployment options include SaaS or self-hosted (Docker/Helm) to accommodate varying compliance and residency requirements.

***

### Security Responsibilities

The following table outlines the division of tasks between your infrastructure and the Toucan AI platform.

| Responsibility              |   Your App / Backend  |     Toucan AI Platform    |
| --------------------------- | :-------------------: | :-----------------------: |
| **User authentication**     |           ✅           |             —             |
| **Token generation**        |           ✅           |             —             |
| **API key storage**         |           ✅           |             —             |
| **Data access control**     | ✅ (Define attributes) | ✅ (Enforce at query time) |
| **Data storage**            |           —           |  ✅ (In SaaS deployments)  |
| **Visualization rendering** |           —           |             ✅             |
| **Row-level security**      |    ✅ (Define logic)   |     ✅ (Enforce logic)     |

***

### Best Practices

* **Server-Side Signing**: Always generate and sign authentication tokens on your backend to prevent client-side tampering.
* **Token Lifespan**: Use short-lived tokens and implement a rotation strategy for API keys.
* **RLS Mandatory**: Apply row-level security as a default for all multi-tenant or sensitive data use cases.
* **Domain Whitelisting**: Strictly restrict allowed origins to your trusted production and development domains.
* **Audit Logs**: Periodically review token scopes and access logs to ensure compliance with internal security policies.