Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Updated on 2026-10-03

Embed SDK — a dashboard inside your system

Display a published dashboard inside your application with a token signed on your server, an iframe, and embed-sdk.js for events and filters — with the step-by-step of the Share screen.

On this page (10)

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:

PieceWhere it runsWhat it does
Embed keyingestia.io (UI)public keyId + secret that only your server knows
Tokenyour serversigned proof that THIS user sees THIS dashboard for N minutes
embed-sdk.jsyour user's browsercreates 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)#

  1. Check Sites allowed to display the dashboard. If your application's domain isn't on the list, ask support.
  2. Choose the Maximum token lifetime (5 minutes, 15 minutes (recommended), 1 hour, or 8 hours (full shift)) and click Turn on embed.
  3. 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). The keyId is public. Ready-made code, with your keyId, is in How to issue the token on your server (copy code button).
  4. Sign the token on your server (never in the browser):
js
// 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}`;
  1. Embed with the SDK:
html
<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 onPronto callback 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 - iat above the ceiling → refused).
  • Origin allowlist via CSP frame-ancestors + Origin/Referer checks on the server; the bridge locks onto the first valid origin of the handshake.
  • The postMessage channel 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.
  • aplicarFiltros with a non-empty state reloads the iframe (the pipeline reads ?f= on mount); apply it right after onPronto. trocarPagina and aplicarFiltros(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 keyId and secret immediately; every issued token stops working. Update INGESTIA_EMBED_SECRET on 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#

SymptomLikely causeWhat to do
Refusal screen / onErro right on openexpired token or origin outside the allowlistissue a new token; ask support to add the domain
Filters don't applyaplicarFiltros before onProntoapply inside/after onPronto
filtros_invalidosinvalid filter structureuse the editor ids; read onEstado to discover them
Every token stopped workingthe secret was rotatedupdate INGESTIA_EMBED_SECRET

Next steps: Authentication · Errors and limits · Support (for the origin allowlist).

Related links