# Token-based access (/core/embed/authentication/token-based-access)



<CalloutContainer type="info">
  <CalloutDescription>
    **Target Audience**: Developers
  </CalloutDescription>
</CalloutContainer>

### TL;DR [#tldr]

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

***

### When to use this [#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 [#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-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 [#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.                                                                                               |

<CalloutContainer type="warning">
  <CalloutDescription>
    **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.
  </CalloutDescription>
</CalloutContainer>

***

### Implementation examples [#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 [#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.