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	Controls access to data source configurations within Toucan AI.
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.