Skip to content

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

Updated on 2026-10-03

Tutorial: embed a dashboard

Embed a dashboard in a third-party portal with an HMAC token, an origin allowlist and the events and filters SDK.

On this page (9)

Embedding means placing an ingestia.bi dashboard inside another website (a customer portal, an internal system) through an <iframe>, with a signed token and an origin allowlist. An optional JS SDK lets the host page listen to events and push filters into the dashboard.

Example workspace: Comércio Aurora Ltda (aurora); fictitious host origin https://portal.example.com.

How it works (overview)#

  1. Your backend requests an embed token (HMAC-SHA256) for a specific dashboard.
  2. You add an <iframe src="/d/embed/<token>"> to the host page.
  3. The server validates Origin/Referer, and the frame-ancestors CSP restricts who can frame the iframe (allowlist).
  4. (Optional) embed-sdk.js connects the page to the iframe via postMessage for events and filters.

Prerequisites#

  • A published dashboard.
  • The host origin (https://portal.example.com) on the environment's embed allowlist.
  • A backend able to generate the embed token (short-lived and ephemeral).

Token and channel security#

  • HMAC-SHA256 token, timing-safe verification, 15-min TTL (12h ceiling), scoped to one dashboard.
  • The token can carry a row scope (for example, only the user's store): it only narrows what the dashboard's policy already allows, never widens it. PII always masked. An unpublished dashboard is refused.
  • The postMessage channel is fail-closed: a message in the wrong format is refused; the bridge pins the first valid origin from the allowlist and only accepts commands from it; replies use an explicit targetOrigin, never *.
  • No message carries a data row, token or secret — the SDK only exchanges the filter state (the same information that already goes in the ?f= URL).

Step by step#

  1. Request the origin to be allowed

    In Share ▸ 2 · Embed in your app, see the Sites allowed to display the dashboard list. If https://portal.example.com isn't on it, ask support, giving them the domain.

  2. Turn on embedding

    Choose the Maximum token lifetime (recommended: 15 minutes (recommended)) and click Turn on embed. Copy the secret — "Copy the secret now — it won't be shown again."

  3. Generate the token on the backend

    Use the code under How to issue the token on your server to sign one token per page load (short TTL), with the user's row scope, if any.

  4. Add the iframe

    On the host page: <iframe src="https://SEU-HOST/d/embed/TOKEN" style="width:100%;height:600px;border:0"></iframe>, or use the SDK.

  5. (Optional) Connect the SDK

    Include embed-sdk.js, subscribe to events (onPronto, onEstado, onErro) and send filters to the dashboard.

  6. Test

    Generate test link shows the dashboard before you write any code. Then open the portal and confirm the loading, the row slice and the filters.

What the SDK offers#

  • Events for the host page (e.g., onErro({codigo}) with codes such as origem_nao_autorizada, timeout_carregamento).
  • Push/read the dashboard's filter state (list, period, range, hierarchy, numeric parameters) — never raw data.
  • Height adjustment and a versioned handshake (v: 1; any other version is refused).
  • Layout per device: inside a narrow iframe (phone, tablet), the dashboard uses the layout the owner arranged for that device.
  • TV mode (?tv=1) does not apply to embeds; for a big screen, use the TV link.

Expected result#

  • The dashboard loads inside the portal only when the origin is on the allowlist.
  • Each visitor sees the RLS slice of the token the backend issued.
  • Filters pushed by the host page are reflected in the dashboard; no sensitive data travels through postMessage.

Common mistakes#

SymptomCauseWhat to do
Blank iframe / origem_nao_autorizadaorigin not on the allowlistask support to allow https://portal.example.com
Every token stopped workingsomeone clicked generate new secret or Disableupdate the secret on the server / Re-enable
"Token expired"the 15-min TTL ran outgenerate a new token per session/page load
Filters ignoredorigin not "pinned" correctlymake sure commands come from the allowlisted origin

Limits and caveats#

  • The origin allowlist is platform-wide, not per workspace.
  • For sharing without embedding, use the public link.

Related#


Last reviewed: 2026-10-03.

Related links