Security boundaries

Target Audience: Developers & Non technical users

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.