Token security

Target Audience: Developers implementing embed authentication with Toucan AI.

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

• PII & personal data

• API security