Token-based access

How to manage permissions through embed tokens

Token-based access is the foundation of secure embedded analytics in Toucan AI. By using signed tokens, you control who can view dashboards, what data they can access, and how long their access lasts—all without exposing sensitive credentials in your frontend.

When generating an embed token, you can include a permissions object to control what the embedded user can do. This allows fine-grained access control at the model level.

Permission Levels

Permission	Description
can_view	Read-only access to the resource
can_edit	Full access (view + create/update/delete)
can_query	Ability to query (AI-specific permission)

Permission Models

Model	Available Permissions	Description
dashboard	can_view, can_edit	View or manage dashboards
chart	can_view, can_edit	View or manage charts
database	can_view, can_edit	View or manage data source configurations (connection settings, tables...)
ai	can_query	Use AI features to query data

💡 Tip

About database permissions The database permission controls access to data source configurations within Toucan AI, not direct access to your source database. can_edit allows managing connection settings and table configurations, while can_view only allows reading data through configured sources.

How Token-Based Access Works

1. User Authenticates with Your App: Your backend authenticates the user using your preferred method (SSO, OAuth, JWT, etc.).

2. Backend Generates a Token: After authentication, your backend creates a signed token using your Toucan AI API key. The token encodes:

   • User identity (distinctId, role)

   • Optional custom attributes (e.g., department, region)

   • Optional permissions object (see above)

   • Expiration time

3. Token Passed to Frontend: The token is sent to your frontend and provided to the embedded Toucan AI component (e.g., <tc-dashboard>).

4. Toucan AI Validates the Token: The embedded component sends the token to Toucan AI, which verifies its signature and attributes before displaying any data.

5. Access Enforced: Toucan AI enforces all access controls, including row-level security, based on the token’s contents.

Usage

Add a permissions object to your token generation request:

JavaScript

fetch('https://toucanai.cloud/api/generate-token', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user: {
      distinctId: 'user-123',
      role: 'explorer'
    },
    permissions: {
      dashboard: 'can_edit',
      chart: 'can_edit'
    }
  })
})
  .then(res => res.json())
  .then(console.log);

Python

import requests

response = requests.post(
    "https://toucanai.cloud/api/generate-token",
    headers={
        "x-api-key": "your-api-key",
        "Content-Type": "application/json"
    },
    json={
        "user": {
            "distinctId": "user-123",
            "role": "explorer"
        },
        "permissions": {
            "dashboard": "can_edit",
            "chart": "can_edit"
        }
    }
)
print(response.json()["token"])

Go

type User struct {
    DistinctId string `json:"distinctId"`
    Role       string `json:"role"`
}

type Permissions struct {
    Dashboard string `json:"dashboard,omitempty"`
    Chart     string `json:"chart,omitempty"`
}

type TokenRequest struct {
    User        User        `json:"user"`
    Permissions Permissions `json:"permissions"`
}

Examples

View-Only Access

Allow users to view dashboards without editing capabilities:

{
  "user": {
    "distinctId": "user-123",
    "role": "explorer"
  },
  "permissions": {
    "dashboard": "can_view",
    "chart": "can_view"
  }
}

Full Edit Access

Allow users to create and modify dashboards and charts:

{
  "user": {
    "distinctId": "user-123",
    "role": "explorer"
  },
  "permissions": {
    "dashboard": "can_edit",
    "chart": "can_edit"
  }
}

AI-Enabled Access

Allow users to query data using AI features:

{
  "user": {
    "distinctId": "user-123",
    "role": "explorer"
  },
  "permissions": {
    "dashboard": "can_view",
    "ai": "can_query"
  }
}

Default Behavior

If no permissions object is provided, the token falls back to role-based permissions. The explorer role has the following default permissions:

Model	Default Permission
dashboard	can_view
chart	can_view
database	can_view
ai	❌ (no access)

🗒️ Note

Token permissions override the default role behavior. This means an explorer can be granted can_edit access through the permissions object, even though explorers are read-only by default.

Best Practices

• Always generate and sign tokens server-side.

• Use short-lived tokens and rotate API keys regularly.

• Include only necessary attributes and permissions.

• Never expose API keys or signing secrets in client-side code.

• Audit and monitor token usage for compliance and security.

Related Documentation

• Generate an embed auth token - Learn how to create authentication tokens

• Embed Dashboard - How to embed dashboards in your application