Authentication models
Embedding analytics securely means choosing the right authentication model for your product and users. Toucan AI supports flexible authentication approaches to fit a variety of integration scenarios, from simple SaaS products to complex, multi-tenant platforms.
Why Authentication Matters
Authentication ensures that only authorized users can access embedded dashboards, charts, and AI assistants. It also enables fine-grained control over what data each user can see, supporting row-level security, multi-tenancy, and compliance requirements.
Supported Authentication Models
1. Token-Based Authentication (Recommended)
How it works:
Your backend authenticates the user (via your own auth system: SSO, OAuth, JWT, etc.).
Your backend generates a signed token (using your Toucan AI API key) that encodes the user’s identity, permissions, and any custom attributes (e.g., organization, department, region).
The token is passed to the embedded Toucan AI component in the frontend.
Toucan AI validates the token and enforces access control and row-level security.
Best for:
Most production use cases
Multi-tenant SaaS platforms
Scenarios requiring row-level security or user-specific data
Benefits:
Secure: API keys and signing logic stay server-side
Flexible: Supports custom attributes and fine-grained access
Scalable: Works with any authentication provider
2. API Key Authentication (For Testing & Development)
How it works:
You use your Toucan AI API key directly to generate tokens in a sandbox or development environment.
API keys should never be exposed in client-side code or production environments.
Best for:
Local development
Testing embedding and integration flows
Benefits:
Quick setup for prototyping
Not recommended for production
3. Single Sign-On (SSO) Integration
How it works:
Your application handles SSO (e.g., SAML, OAuth, OpenID Connect) for user authentication.
After authentication, your backend generates a Toucan AI token for the user session.
The rest of the flow is identical to token-based authentication.
Best for:
Enterprise deployments
Organizations with centralized identity providers
How to Choose
For most use cases: Use token-based authentication, generated server-side after your own user authentication.
For internal tools or demos: API key authentication is acceptable, but never expose keys in production.
For enterprise SSO: Integrate your SSO provider and generate tokens after successful login.
Example Flow
Best Practices
Always generate and sign tokens server-side.
Never expose API keys or signing secrets in client-side code.
Use short-lived tokens and rotate API keys regularly.
Include only necessary attributes in tokens for access control and row-level security.
Toucan AI’s authentication models are designed to be secure, flexible, and easy to integrate—so you can deliver embedded analytics with confidence.
Last updated