# Generate a token via API (/core/embed/authentication/how-to/generate-a-token-via-api)



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

### Goal [#goal]

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

***

### Prerequisites [#prerequisites]

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

***

### Steps [#steps]

#### 1. Secure your environment [#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.

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

#### 2. Call the `/generate-token` endpoint [#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 [#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 [#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 [#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](/core/embed/embedding-overview/how-to/embed-a-dashboard) or [How-to: Configure Row-Level Security (RLS)](/core/embed/permissions-and-row-level-security/how-to/apply-rls-to-your-database)