Embed chart partner integration

Headlight embeds the household chart in your app via a cross-origin iframe on embed.withheadlight.com. Your browser sends chart data directly into the iframe with postMessage. Headlight servers never receive names, trusts, or relationship data.

Quickstart

Provision an API key with the embed:chart permission.
Mint a short-lived token from your server:

curl -X POST https://app.withheadlight.com/api/v1/embed/chart-sessions \
  -H "Authorization: Bearer idx_..." \
  -H "Content-Type: application/json" \
  -d '{"frameOrigin":"https://your-app.example.com"}'

Mount the iframe from the pinned embed version and post the render message after ready:

<iframe
  id="headlight-chart"
  sandbox="allow-scripts allow-same-origin"
  style="width:100%;height:720px;border:0"
></iframe>
<script>
  const embedOrigin = "https://embed.withheadlight.com";
  const version = "0.1.0";
  const frameOrigin = "https://your-app.example.com";
  const iframe = document.getElementById("headlight-chart");
  iframe.src = `${embedOrigin}/chart/v${version}/index.html`;

  window.addEventListener("message", (event) => {
    if (event.origin !== embedOrigin || event.source !== iframe.contentWindow) return;
    if (event.data?.type !== "ready") return;
    iframe.contentWindow.postMessage(
      { type: "render", v: 1, token, payload: chartData },
      embedOrigin
    );
  });
</script>

Pin an immutable version prefix (/chart/v0.1.0/index.html). Do not load /chart/latest.

Sandbox attribute

Use exactly sandbox="allow-scripts allow-same-origin". Do not add allow-top-navigation or allow-popups.

Token role

The token is for metering and licensing. Framing is enforced by the embed CSP frame-ancestors directive, not by the token.

Next steps

⌘I