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