docs/content/product/embedding/signed-embedding.mdx
Signed embedding is designed for external, customer-facing analytics. It uses JWT tokens for seamless authentication, making it ideal for:
Users authenticate through your application without needing Cube accounts, providing a seamless experience. The session tokens are cryptographically signed to ensure secure access with user-specific permissions.
Signed embedding works through a two-step authentication flow:
Session lifecycle:
This ensures secure authentication while maintaining a smooth user experience.
To use the embedded chat or dashboard, you need an API key:
Use the Generate Session API to create a session for your user. This endpoint will automatically create (insert) or update the external user based on the externalId provided.
const API_KEY = "YOUR_API_KEY";
const DEPLOYMENT_ID = 32;
const session = await fetch(
"https://your-account.cubecloud.dev/api/v1/embed/generate-session",
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Api-Key ${API_KEY}",
},
body: JSON.stringify({
deploymentId: DEPLOYMENT_ID,
externalId: "[email protected]",
userAttributes: [
// optional - enables row-level security
{
name: "city",
value: "San Francisco",
},
{
name: "department",
value: "Sales",
},
],
}),
},
);
const data = await session.json();
const sessionId = data.sessionId;
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>
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 DEPLOYMENT_ID = 32;
const externalId = "[email protected]";
const sessionResponse = await fetch(
`${API_BASE_URL}/api/v1/embed/generate-session`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Api-Key ${API_KEY}`,
},
body: JSON.stringify({
deploymentId: DEPLOYMENT_ID,
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>
You can pre-set dashboard filter values by adding URL parameters in the format
?f_<semantic_view>.<dimension>=<JSON>. The <semantic_view> and <dimension>
must match the internal names (not display titles) of the semantic view and
dimension configured on the filter widget. If the filter type is omitted, it
defaults to equals.
Example:
https://your-tenant.cubecloud.dev/embed/dashboard/YOUR_DASHBOARD_PUBLIC_ID?session=YOUR_SESSION_ID&f_orders_transactions.users_country={"value":"USA"}
This works on both regular and published (embedded) dashboards. The filter is only applied if a matching filter widget for that dimension already exists on the dashboard.
You can customize the appearance of your dashboard — including background, widget styling, borders, titles, and fonts — using the <Btn>Styling</Btn> pane in the Dashboard Builder. Open your dashboard, click <Btn>Dashboard Builder</Btn> in the top bar, then click the gear icon to open the <Btn>Styling</Btn> panel.
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.
<InfoBox> User attributes must first be configured in your Cube admin panel. See the [User Attributes documentation](/product/administration/users-and-permissions/user-attributes) for setup instructions. </InfoBox>How it works:
city, department)Example use cases:
For a complete working example of signed embedding, check out the cube-embedding-demo repository. This demo application provides:
You can clone the repository, configure it with your Cube credentials, and run it locally to test embedding functionality or use it as a reference implementation for your own application.