Toucan AI Docs
EmbedAuthentication

Copy of 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

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.

Summary

Toucan AI’s authentication models are designed to be secure, flexible, and easy to integrate—so you can deliver embedded analytics with confidence.

On this page

Why Authentication MattersSupported Authentication Models1. Token-Based Authentication (Recommended)2. API Key Authentication (For Testing & Development)3. Single Sign-On (SSO) IntegrationHow to ChooseExample FlowBest PracticesSummary