Iframe & Token Lifecycle

Your backend issues a bootstrap URL through POST /partner/embed-sessions. The parent receives no bearer token:

{
  "embedUrl": "https://portal.vrplatform.app/reports/trial-balance#code=<one-time-code>",
  "teamId": "4f8f94de-2cc0-4ec7-a7f8-f0c7f560e59a",
  "expiresAt": "2026-07-19T12:01:00.000+00:00"
}

Mounting

Set embedUrl directly as the iframe src. Do not parse the fragment, put the code in a query parameter, or call the exchange endpoint from the parent:

<iframe
  src="https://portal.vrplatform.app/reports/trial-balance#code=<one-time-code>"
  title="Profit and loss"
></iframe>

The iframe calls POST /embed-sessions/exchange from the configured portal origin. The exchange atomically consumes the code, returns a 15-minute JWT, and the embedded app immediately clears the fragment. The JWT stays in memory and is bound to one partner, team, user, audience, and scope set.

Because the code is single-use and the cleared URL contains no session, a plain iframe reload cannot restore access. Request a new bootstrap URL and replace src instead. The expiresAt returned by session issuance is the 60-second bootstrap deadline, not the bearer-token expiry; mount immediately.

No Message Protocol

The embed does not send or receive postMessage events. There is no ready, resize, token replacement, or expiry message. Your product owns the shell:

• Sizing — give the iframe fixed or responsive dimensions.
• Refresh — remount periodically with a newly issued bootstrap URL; use a cadence shorter than the 15-minute session policy.
• Expiry — if a session expires, request a new URL and remount.

Frontend Flow

1. Ask your backend for a bootstrap URL.
2. Mount the iframe before the 60-second bootstrap expiry.
3. Keep the iframe scoped to the returned team.
4. Remount with a fresh URL before the 15-minute session window ends.
5. On access or team change, discard the iframe and start a new session.

Do not persist the URL, code, or session token in local storage or telemetry, and never use the partner API key in the browser.

See UI States for shell behavior.