> 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/govern/security-model/token-security.md).

# Token security

{% hint style="info" %}
**Target Audience**: Developers implementing embed authentication with Toucan AI.
{% endhint %}

### TL;DR

Embed access uses **short-lived, encrypted tokens**. Your **API key stays on your server** and is only used to mint tokens. Tokens carry user identity, permissions, and optional attributes for row-level security.

***

### When to use this

Use this page when implementing [token-based embed access](/embed/authentication/token-based-access.md) or reviewing embed security for a security questionnaire.

***

### Token properties

| Property       | Behavior                                                            |
| -------------- | ------------------------------------------------------------------- |
| **Encryption** | Tokens are encrypted (JWE, AES-256-GCM)                             |
| **Lifetime**   | Short-lived — default **one hour**                                  |
| **Contents**   | Organization, embed user identity, permissions, optional attributes |
| **API keys**   | Never exposed in the browser; server-side only                      |

Each API key has a cryptographically isolated signing/encryption context so tokens from one key cannot be decrypted with another.

***

### Best practices

* **Generate tokens on your backend** after you have authenticated the end user.
* **Refresh tokens** before expiry for long-lived sessions.
* **Minimize token payload**: only attributes required for RLS and product behavior.
* **Never embed API keys** in frontend code, mobile apps, or public repositories.
* Combine tokens with **row-level security** on all sensitive data.

***

### Related pages

* [Security boundaries (embed)](/embed/embedding-overview/security-boundaries.md)
* [PII & personal data](/govern/security-model/pii-and-personal-data.md)
* [API security](https://github.com/ToucanToco/toucan-ai/blob/main/docs/govern/security-model/api-security.md)