Generate a token via API

To embed a dashboard in your application, you first need to generate an embed auth token. This token authorizes access to the dashboard for a specific user and must be generated from your backend.

Objective

This tutorial shows you how to programmatically generate an access token for embedding dashboards or charts by calling the /generate-token API endpoint. This is useful for server-side integrations, automation, or custom workflows.

Prerequisites

• A Toucan AI account

• An API key with permission to generate tokens

• The base URL for your Toucan AI instance (e.g., https://your-instance.toucan.ai)

Steps

1. Create an API Key

Go to your application User Settings. Generate an API Key (it will be used by your backend to authenticate with our API). Store this key securely.

❗Caution Important Security Notice This "Create Embed Authorization" request must happen server-side only. You do not want to expose your API key or embed token client-side, as that would allow end users to:

• change filters or parameters themselves,

• or even gain direct access to your secured dashboards and datasets.

Never use your API key or token in the frontend!

2. Call the /generate-token endpoint

From your backend, make a POST request to the /api/generate-token endpoint of your Toucan instance:

• Cloud (SaaS): https://toucanai.cloud/api/generate-token

• Self-hosted: https://your-domain.com/api/generate-token

Example requests

Bash

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"user": {"distinctId": "user-123", "role": "explorer"}}' \
  https://toucanai.cloud/api/generate-token

JavaScript

fetch('https://toucanai.cloud/api/generate-token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ user: { distinctId: 'user-123', role: 'explorer' } })
})
  .then(res => res.json())
  .then(console.log);

Python

import requests
headers = {
    'Authorization': 'Bearer <API_KEY>',
    'Content-Type': 'application/json',
}
data = {"user": {"distinctId": "user-123", "role": "explorer"}}
response = requests.post('https://toucanai.cloud/api/generate-token', json=data, headers=headers)
print(response.json())

Go

package main
import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
)
func main() {
  payload := map[string]interface{}{
    "user": map[string]string{
      "distinctId": "user-123",
      "role": "explorer",
    },
  }
  b, _ := json.Marshal(payload)
  req, _ := http.NewRequest("POST", "https://toucanai.cloud/api/generate-token", bytes.NewBuffer(b))
  req.Header.Set("Authorization", "Bearer <API_KEY>")
  req.Header.Set("Content-Type", "application/json")
  client := &http.Client{}
  resp, _ := client.Do(req)
  defer resp.Body.Close()
  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)
  fmt.Println(result)
}

Request Body Parameters

Field	Type	Required	Description
user	object	✅	User information object

User Object Properties

Field	Type	Required	Description
distinctId	string	✅	Unique user identifier for tracking in logs and traces
role	"explorer"	✅	User role (explorer-only currently)

Response

On success, the endpoint returns a JSON object containing the embed token:

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

Copy this token for use in embedding dashboards or charts.

3. Use the Token

Use the generated token in your embedding integration as described in the Authentication & Tokens guide.

Security Best Practices

• Never expose your API key or token generation endpoint to client-side code.

• Always generate tokens server-side.

• Store API keys securely (e.g., environment variables, secret managers).

Conclusion

Congratulations! You have successfully generated a token via the Toucan AI API. Programmatic token generation allows you to automate secure access for embedding analytics, ensuring each user receives the correct data and permissions in your application.