> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/embed/authentication/token-based-access.md).

# Token-based access

{% hint style="info" %}
**Target Audience**: Developers
{% endhint %}

### 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.                      |

{% hint style="warning" %}
**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.
{% endhint %}

***

### 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:**

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toucanai.cloud/embed/authentication/token-based-access.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.