Embedding

Cube supports embedding the analytics chat interface directly into your applications via an iframe or API.

Embedding the chat interface allows you to give users a guided, semantic-layer-aware data assistant anywhere in your product or portal. Embedding dashboards allows you to display interactive dashboards anywhere in your product or portal.

Getting started

Enable embedding

To enable the embedding feature:

You must have admin privileges in your Cube instance.
Go to Admin → API → Embed
Click Enable Embedding.

Once enabled, you'll be able to generate embed sessions using your API key.

Get your API key

To use the embedded chat or dashboard, you need an API key:

Go to Access → API Keys in your Cube admin panel
Generate or copy your existing API key.
You'll use this key to authenticate API calls for generating embed sessions.

Generate an embed session

Use the /api/v1/embed/generate-session endpoint to create a session for your user. This endpoint will automatically create (insert) or update the external user based on the externalId provided.

Accounts are limited to 10,000 external users. To increase this limit, please contact support.

Example (JavaScript)

const API_KEY = "YOUR_API_KEY";
 
const session = await fetch(
  "https://your-tenant.cubecloud.dev/api/v1/embed/generate-session",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Access-Token ${API_KEY}",
    },
    body: JSON.stringify({
      externalId: "user@example.com",
      userAttributes: [
        // optional - enables row-level security
        {
          name: "city",
          value: "San Francisco",
        },
        {
          name: "department",
          value: "Sales",
        },
      ],
    }),
  },
);
 
const data = await session.json();
const sessionId = data.sessionId;

Embedding via iframe

Use the session ID to embed the chat UI or the dashboard UI in your application:

<iframe
  title="Analytics Chat"
  src="https://your-tenant.cubecloud.dev/embed/chat?sessionId=YOUR_SESSION_ID"
></iframe>

<iframe
  title="Dashboard"
  src="https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID"
  width="100%"
></iframe>

Complete example

Here's a complete HTML example that demonstrates the full flow for embedding a dashboard:

<html>
  <head>
    <script>
      (async () => {
        const API_BASE_URL = "https://your-tenant.cubecloud.dev";
        const API_KEY = "YOUR_API_KEY";
        const externalId = "user@example.com";
 
        const sessionResponse = await fetch(
          `${API_BASE_URL}/api/v1/embed/generate-session`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              Authorization: `Access-Token ${API_KEY}`,
            },
            body: JSON.stringify({
              externalId: externalId,
            }),
          },
        );
 
        const sessionData = await sessionResponse.json();
 
        const iframe = document.getElementById("dashboard-iframe");
        const baseUrl =
          "https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID";
        iframe.src = `${baseUrl}?session=${sessionData.sessionId}`;
      })();
    </script>
  </head>
 
  <body>
    <iframe
      id="dashboard-iframe"
      src=""
      width="100%"
      height="800"
      frameborder="0"
      allowtransparency="true"
      allowfullscreen="true"
    ></iframe>
  </body>
</html>

User attributes

User attributes enable row-level security and personalized chat responses by filtering data based on user permissions. The attributes you pass during session generation automatically filter data queries and responses.

User attributes must first be configured in your Cube admin panel. See the User Attributes Administration Guide for setup instructions.

How it works:

Configure attributes in your admin panel (e.g., city, department)
Pass attributes during session generation
Data is automatically filtered based on user permissions through access policies
AI responses are personalized to the user's context

Example use cases:

Sales reps only see data for their assigned territory
Regional managers see data filtered by their city
Department heads see only their department's metrics

Security considerations

API Key Security: Keep your API keys secure and never expose them in client-side code
Session Management: Sessions are temporary and should be regenerated as needed
HTTPS: Always use HTTPS in production environments

Troubleshooting

Common issues

Invalid Session ID: Ensure the session ID is valid and hasn't expired
Dashboard Not Found: Verify the dashboard public ID is correct and the dashboard is published
Authentication Errors: Check that your API key is valid and has the necessary permissions
CORS Issues: Ensure your domain is properly configured for embedding

Getting help

If you encounter issues with dashboard embedding:

Check the browser console for error messages
Verify your API key and session generation
Ensure the dashboard is published and accessible
Contact support if you need assistance with configuration

Queries Chat API