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


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.toucanai.cloud/embed/embedding-overview/security-boundaries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.