Token-based access

Target Audience: Developers

TL;DR

Toucan AI uses signed authentication tokens to define granular user permissions and session lifespan without exposing backend credentials.

When to use this

Use this page to configure the permissions object during token generation to control specific user actions, such as editing dashboards or querying the AI assistant.

Fine-grained permissions

The authentication token includes a permissions object that determines the available actions for the embedded user. This model allows for precision control at the resource level.

Permission levels

Permission	Description
can_view	Grants read-only access to the specified resource.
can_edit	Grants full access to view, create, update, and delete the resource.
can_query	Specifically enables the use of the AI assistant for data exploration.

Permission models by resource

Model	Available Permissions	Description
dashboard	`can_view`, `can_edit`	Controls the ability to view or manage dashboards.
chart	`can_view`, `can_edit`	Controls the ability to view or manage individual charts.
database	`can_view`, `can_edit`, `can_query`	Controls access to data source configurations within Toucan AI. `can_query` only runs queries, as a custom front reading its data needs.
ai	`can_query`	Grants permission to use the AI assistant.

Note: Database permissions control the management of connection settings and table metadata within Toucan AI; they do not grant direct write access to your source database.

Implementation examples

To generate a token with specific permissions, perform an HTTP POST request to the /embed/generate-token endpoint.

Your request must include:

The x-api-key header with your API key
The Content-Type: application/json header
A JSON body containing the user and permissions objects

Example request body:

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

1. View-only access

Restricts users to reading data without the ability to modify visualizations.

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

2. Full edit access

Allows users to create and modify both dashboards and charts.

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

3. AI-enabled exploration

Allows users to view dashboards and perform ad-hoc queries via the AI assistant.

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

Constraints and defaults

Default Fallback: If no permissions object is provided, Toucan AI defaults to can_view for dashboards, charts, and databases, with no AI access (❌).
Permission Overrides: Explicit token permissions override default role behavior. For example, a user with an "explorer" role can be granted can_edit access through the token.
Security: Tokens must be generated and signed server-side. API keys must never be exposed in client-side code.

Token-based access

TL;DRCopy Anchor Link

When to use thisCopy Anchor Link

Fine-grained permissionsCopy Anchor Link

Permission levelsCopy Anchor Link

Permission models by resourceCopy Anchor Link

Implementation examplesCopy Anchor Link

Constraints and defaultsCopy Anchor Link