Embed a self-service dashboard editor

GoalCopy Anchor Link

Configure and embed a self-service dashboard editor into your application so end users can create their own dashboards from scratch.

Each dashboard is personal to the authenticated user and linked to the provided auth-token.

What this enables:

• End users create dashboards without leaving your app
• Dashboard ownership is scoped per user token

PrerequisitesCopy Anchor Link

• A Toucan AI account and active organization.
• Credentials for a supported SQL database (e.g., PostgreSQL).
• A code editor or environment for testing HTML/web components (e.g., CodePen).

StepsCopy Anchor Link

1: Create an API KeyCopy Anchor Link

• Navigate to your Account settings page by clicking on your profile icon in the bottom left corner, then go to the API Keys section.
• Create a new API Key. Copy it and store it securely.

This key will be used on your backend server to securely generate authentication tokens for your embedded application.

2: Implement a user attribute modelCopy Anchor Link

(Optional) Define the attributes that will contextually personalize the experience for your users.

Register User Attributes

• Navigate to Settings > Embed & access.
• In the Token Attributes section, click Add an attribute.
• Define the traits you need (e.g., name: region, type: String). These must match the keys you will send in your user tokens.

3: Connect to a DatabaseCopy Anchor Link

• Navigate to the Database tab from the Home Page.
• Click Add a Database and select a connector.
• Input connection details including Host, Username, Password, and Database name.
• Click Test Connection, then click Connect.

How-To: Add a database

4: Complete Metadata InformationCopy Anchor Link

• Review existing table and column descriptions for accuracy.
• (Recommended): Click Analyze from the database More options menu (⋮) to start an AI analysis run on selected schemas and tables.
  • The AI proposes descriptions, display names, and type casts — nothing is applied until you review and confirm.
  • Open AI analyses from the same menu to review proposals by kind (type casts, display names, descriptions).
  • Confirm each section to apply accepted proposals to your metadata.
• Ensure critical columns are described plainly to improve future AI prompt results.

How-To: Analyze your database with AI · Review AI analysis proposals

5: Define Row-Level Security (RLS)Copy Anchor Link

Secure your data so users only see what they are authorized to access.

1. Go to the Database tab and select a table.
2. In the Access rules section, map a User Attribute to a specific dataset field (a column of the table).
   • Example: Map the user.region attribute to the sales_region column.

This ensures that the AI automatically applies a filter (e.g., WHERE sales_region = "North") based on the user attribute.

How-To: Apply RLS to your database

6: Behavior and user scope Copy Anchor Link

• The embedded editor lets users create dashboards from scratch.
• Each user only accesses their own dashboard workspace.
• A different auth-token results in a different personal dashboard context.

7: Get an auth tokenCopy Anchor Link

For testing and configuration, you can generate a temporary token directly from the Toucan AI interface.

• Navigate to Settings > Embed & access.
• Scroll down to the Token Generation Sandbox section.
• Paste your API Key.
• Under User Attributes, configure the values for any custom attributes as well as the aiContextClues for this token.
• Click Generate Token and copy the resulting string.

8: Configure CORS and embed the dashboard editorCopy Anchor Link

Before your embed can render, you must authorize the domain where it will be hosted.

• In the Embed & access settings, locate the Authorized Origins section.
• Add the URL of your application or development environment (e.g., https://codepen.io) and click Save.

• Copy the <tc-self-service-dashboard/> web component code:

<script type="module" src="https://toucanai.cloud/embed/embed.js"></script>

<tc-self-service-dashboard
  server-url="https://toucanai.cloud/api"
  auth-token="your-auth-token"
  data-theme="light">
</tc-self-service-dashboard>

• Paste the code into your application's HTML.
• Replace the Auth-Token placeholder with your generated token.

Once the token has been copied into the web component, this is what it looks like (here on codepen.io, for example).

ConclusionCopy Anchor Link

You have successfully embedded a self-service dashboard editor.
Your end users can now create and manage their own personal dashboards directly in your application, with each dashboard securely tied to the user’s authentication token.