> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withheadlight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

# 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

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

```bash theme={null}
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"}'
```

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

```html theme={null}
<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

* [Schema reference](/embed/schema-reference)
* [Mapping guide](/embed/mapping-guide)
* [postMessage protocol](/embed/postmessage-protocol)
* [Token minting](/embed/token-minting)
* [Security appendix](/embed/security-appendix)
* [Verification runbook](/embed/verification-runbook)
* [Known footguns](/embed/known-footguns)