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