Embedded Query Builder

Give your customers Query Builder inside your own product: they pick fields, filter, group, calculate and chart, without writing SQL. Each customer sees only their own data. Embedded Canvas applies your tenant filter to every query, and your customer column is hidden from the field list and can't be used in a query.

It runs on the views you publish in Business Model, so build and publish those first.

1. Mint a session on your backend

Call the session API from your server with your embed API key (from Embed in the Operator console). Never do this in the browser.

POST https://api.embeddedcanvas.com/public/metrics/v1/sessions
Authorization: Bearer {EMBED_API_KEY}
Content-Type: application/json

{
 "customerId": "acme-123",
 "allowedOrigins": ["https://app.yourproduct.com"],
 "capabilities": ["metrics:explore"],
 "views": ["Sales", "Inventory"],
 "ttlSeconds": 900
}

Field
`customerId`	Required. The tenant value for the signed-in end user, the same one you use for dashboards.
`allowedOrigins`	Required. The web origins of your app that will show the iframe. Only these can frame it and talk to it.
`capabilities`	Must include `metrics:explore`. It's never granted unless you ask for it.
`views`	Optional. Names of the published views this customer may use. Leave it out to allow every published view.
`ttlSeconds`	Optional. 15 minutes at most (900).

The response has token and expiresAt. Return the token to your front end.

2. Show it in an iframe

<iframe
 src="https://embeddedcanvas.com/embed/query-builder/{token}"
 style="width:100%;height:800px;border:0"
 title="Query Builder"></iframe>

The page refuses to load inside any site that isn't in the session's allowedOrigins.

3. Keep the session going

A minute before the session ends, the iframe asks your page for a new token. Mint one on your backend for the same customer and send it back. A token for a different customer is ignored.

window.addEventListener("message", async (e) => {
 if (e.origin !== "https://embeddedcanvas.com") return;
 if (e.data?.type !== "ec:explore-token-request") return;
 const { token } = await fetch("/api/query-builder-session").then((r) => r.json); // your backend
 e.source.postMessage({ type: "ec:explore-token", token }, e.origin);
});

If no new token arrives, the page tells the user their session ended and to reload.

What your customers can do

Pick fields from the allowed views, filter (text filters ignore upper and lower case), group, sort and Top N
Calculations and formulas
List, crosstab and charts, with subtotals and totals
Click a number to see the records behind it
Compare with the previous period or the same period last year

Not available embedded: saving or sharing queries, schedules, file uploads, exports, the AI features (Ask and Explain), View as, Add to Dashboard builder, and Business Model changes.

Security

Keep the embed API key on your server. Mint a short session per user.
Map your signed-in user to customerId on the server, never from a value the browser sends.
Treat the iframe URL like a password for its 15 minutes: don't log it or share it.