Generate a token via API

GoalCopy Anchor Link

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

PrerequisitesCopy Anchor Link

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

StepsCopy Anchor Link

1. Secure your environmentCopy Anchor Link

• 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.

2. Call the /generate-token endpointCopy Anchor Link

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

3. Process the responseCopy Anchor Link

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 practicesCopy Anchor Link

• 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.

ConclusionCopy Anchor Link

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)