Generate a token via API

Target Audience: Developers

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 with an active instance.

• A valid API key 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.

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.

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

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:

{
  "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 or How-to: Configure Row-Level Security (RLS)