> 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/how-to/generate-a-token-via-api.md).

# Generate a token via API

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

### Goal

Implement a server-to-server POST request to the Toucan AI `/generate-token` endpoint to retrieve a signed access token.

***

### Prerequisites

* A [Toucan AI account](/getting-started/quick-start/subscribe-to-toucan.md) with an active instance.
* A [valid API key](/embed/authentication/how-to/generate-an-api-key.md) with permissions to generate tokens.
* Knowledge of your instance's base URL (SaaS or self-hosted).

***

### Steps

#### 1. Secure your environment

* Obtain your API key from the **User Settings** in Toucan AI.
* Store the API key in a secure server-side environment variable or secret manager.

{% hint style="danger" %}
**Security Alert**: This request must remain server-side. Exposing the API key or token generation logic in the frontend allows users to bypass security filters and access unauthorized datasets.
{% endhint %}

#### 2. Call the `/generate-token` endpoint

Make a POST request to the relevant URL for your deployment:

* Cloud (SaaS): `https://toucanai.cloud/embed/generate-token`

**HTTP request example**

```http
POST /embed/generate-token HTTP/1.1
Host: toucanai.cloud
x-api-key: <YOUR_API_KEY>
Content-Type: application/json

{
  "user": {
    "distinctId": "user-123",
    "role": "explorer",
    "attributes": {}
  }
}
```

**Request body parameters**

| Parameter           | Type   | Required | Description                                              |
| ------------------- | ------ | -------- | -------------------------------------------------------- |
| **user**            | object | ✅        | Contains the identity and role of the target user.       |
| **user.distinctId** | string | ✅        | A unique identifier used for tracking and auditing logs. |
| **user.role**       | string | ✅        | The user's role (currently "explorer").                  |
| **user.attributes** | object | ✅        | Custom metadata for the user (e.g., RLS, custom traits). |

#### 3. Process the response

On success, the API returns the token and its expiration duration:

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": "1h"
}
```

* Extract the `token` string and pass it to your frontend for use in the `<tc-dashboard>` or `<tc-ai-assistant>` components.

***

#### Security best practices

* **Server-side only**: Never call this endpoint from client-side code.
* **Protect credentials**: Use environment variables to handle API keys; do not hardcode them in your source files.
* **Short lifespans**: Use the token immediately for the session, as it is designed to expire.

***

### Conclusion

Programmatic token generation ensures that every user in your application receives a secure, unique session authorized by your backend. This workflow is the standard for production-grade embedded analytics.

**Suggested Next Step**: [How-to: Embed a dashboard](/embed/embedding-overview/how-to/embed-a-dashboard.md) or [How-to: Configure Row-Level Security (RLS)](/embed/permissions-and-row-level-security/how-to/apply-rls-to-your-database.md)


---

# 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/how-to/generate-a-token-via-api.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.