Embed chart

Embed the household chart in your app with an iframe on embed.withheadlight.com. Your browser sends chart data 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"}'

Load a pinned embed version and post render after ready. See Embed with React for the React component.

HTML
React

<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 iframe = document.getElementById("headlight-chart");

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
);
});
iframe.src = `${embedOrigin}/chart/v${version}/index.html`;

</script>

<HeadlightChart token={token} data={chartData} version="0.1.0" />

Copy HeadlightChart from Embed with React. Use the Calderwood sample payload as chartData.

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

Mint the token on your server. Your page origin must be allowlisted. The token is required to render.

Next steps