The origin allowlist applies to the whole instance today (not yet per workspace).
Display a published ingestia.io dashboard inside your application, with a signed token (lifetime and scope), events (loaded, filtered, changed page), and programmatic filters — in the spirit of Power BI Embedded, with no capacity cost.
The pieces:
| Piece | Where it runs | What it does |
|---|---|---|
| Embed key | ingestia.io (UI) | public keyId + secret that only your server knows |
| Token | your server | signed proof that THIS user sees THIS dashboard for N minutes |
embed-sdk.js | your user's browser | creates the iframe, delivers events and commands |
Availability#
- Status: available. Availability follows your plan's SLA (99.5% monthly from Growth up).
- Where to turn it on: in the dashboard, More actions ▸ share ▸ card 2 · Embed in your app.
- Region: Brazil (São Paulo).
Permissions#
- Turning on embed, rotating the secret, and disabling are workspace actions (recorded in the audit log).
- The token opens only one dashboard (the signed
dashboardId) — never another. - The optional row scope in the claims (
f) only narrows what the dashboard's policy already allows; it never widens it. PII is always masked.
Setup (step by step)#
- Check Sites allowed to display the dashboard. If your application's domain isn't on the list, ask support.
- Choose the Maximum token lifetime (5 minutes, 15 minutes (recommended), 1 hour, or 8 hours (full shift)) and click Turn on embed.
- Copy the secret — "Copy the secret now — it won't be shown
again." Store it as an environment variable on your server (e.g.,
INGESTIA_EMBED_SECRET). ThekeyIdis public. Ready-made code, with yourkeyId, is in How to issue the token on your server (copy code button). - Sign the token on your server (never in the browser):
// Node.js — RUN THIS ON YOUR SERVER. The secret never goes to the browser.
import { createHmac, randomBytes } from "node:crypto";
const SEGREDO = process.env.INGESTIA_EMBED_SECRET;
const claims = {
k: "SEU_KEY_ID", w: "SEU_WORKSPACE_ID", d: "SEU_DASHBOARD_ID",
iat: Math.floor(Date.now() / 1000),
exp: Math.floor(Date.now() / 1000) + 900, // 15 min
n: randomBytes(16).toString("base64url"),
// f: { c: "loja", v: ["12"] }, // row scope (optional)
};
const corpo = "v1." + claims.k + "." + Buffer.from(JSON.stringify(claims)).toString("base64url");
const token = corpo + "." + createHmac("sha256", SEGREDO).update(corpo).digest("base64url");
const urlDoEmbed = `https://ingestia.io/d/embed/${token}`;- Embed with the SDK:
<div id="painel"></div>
<script src="https://ingestia.io/embed-sdk.js"></script>
<script>
var painel = IngestiaEmbed.criar({
container: "#painel",
url: urlDoEmbedVindaDoSeuServidor, // /d/embed/<token>
autoAltura: true,
onPronto: function (p) { /* { dashboardId, pagina } */ },
onEstado: function (e) { /* { f, filtros } — state only, never rows */ },
onInteracao: function (i) { /* { tipo: "pagina" | "drill", resumo } */ },
onErro: function (err) { /* { codigo } — expired token: issue another one */ },
});
// Commands: painel.trocarPagina(1); painel.aplicarFiltros({...}); painel.destruir();
</script>Validation (how to confirm it worked)#
- The
onProntocallback fires with{ dashboardId, pagina }when the bridge responds — a sign that the token was accepted and the dashboard rendered. - A token with an invalid signature, an expired token, an unpublished dashboard, or an origin outside the
allowlist → the dashboard refuses (refusal screen /
onErro). - Generate test link, on the Share screen, opens the dashboard with a test token so you can validate the iframe before writing code.
- In a narrow iframe (phone, tablet), the dashboard uses the layout the owner
arranged for that device. TV mode (
?tv=1) doesn't apply to embed.
Example#
Your SaaS application shows each logged-in customer their own dashboard with
f: { c: "loja", v: ["<id da loja do cliente>"] } in the claims — the same dashboard,
filtered by row, with a 15-min token issued on every page load.
Cost#
- Embed has no capacity cost (unlike Power BI Embedded). The cost is that of processing the dashboard's own queries, as in native BI.
Security#
- HMAC-SHA256 signature checked in constant time before any
other rule; there is no eternal token (
exp - iatabove the ceiling → refused). - Origin allowlist via CSP
frame-ancestors+Origin/Refererchecks on the server; the bridge locks onto the first valid origin of the handshake. - The
postMessagechannel never carries data rows, the token, or the secret — only the filter state (the same one already visible in the iframe URL's?f=). - Never generate the token in the browser: the secret must not reach the client.
Limits#
- Lifetime: default 15 min; ceiling per key; absolute ceiling 12 h.
- The origin allowlist is platform-wide today (configured by us);
a per-workspace allowlist is on the
Roadmap. Ask support to add your application's domain. aplicarFiltroswith a non-empty state reloads the iframe (the pipeline reads?f=on mount); apply it right afteronPronto.trocarPaginaandaplicarFiltros(null)don't reload.- Cross-filter events (click on a bar/slice) are not emitted yet
(
Roadmap).
Rotation and revocation (in the UI)#
- generate new secret — asks for confirmation (Generate new) and swaps
keyIdandsecretimmediately; every issued token stops working. UpdateINGESTIA_EMBED_SECRETon your server. - Disable — refuses any token, even with a valid signature. Re-enable turns it back on.
- Unpublishing the dashboard — cuts off the embed along with it.
Troubleshooting#
| Symptom | Likely cause | What to do |
|---|---|---|
Refusal screen / onErro right on open | expired token or origin outside the allowlist | issue a new token; ask support to add the domain |
| Filters don't apply | aplicarFiltros before onPronto | apply inside/after onPronto |
filtros_invalidos | invalid filter structure | use the editor ids; read onEstado to discover them |
| Every token stopped working | the secret was rotated | update INGESTIA_EMBED_SECRET |
Next steps: Authentication · Errors and limits · Support (for the origin allowlist).