Embedded authorize

Open the agent-authorization page in a modal on your own site — allowlist-framed, origin-checked messaging, no redirect.

By default the authorize page refuses to be framed (it’s where users grant spending authority — clickjacking matters). A merchant can register up to three origins that may embed it — production and staging, say — and everything below hangs off that list.

Building a chat or single-page app? The consent component in SDK 0.4.0 keeps the buyer inside your page with no cookies and no redirect — see Buyer purchases inside your chat. The modal below remains the right fit for a classic site.

​

1 · Register your embed origin

PATCH /v1/integration/merchants/{merchantId}
{ "embedOrigin": "https://yourshop.example https://staging.yourshop.example" }

Up to three bare origins, space- or comma-separated: https, no path or query (http only for localhost and 127.0.0.1); null clears them. Once set, the authorize page serves frame-ancestors 'self' <your origins> and drops X-Frame-Options — your iframe renders; everyone else’s stays blocked. The same list is where the page posts its messages, and which browser origins may call the buyer API with a bearer (Browser access and CORS).

On Adyen? This list is your site. Adyen keeps a separate allowed-origins list on your API credential, and that one needs Alyte’s origin, not yours — see Connect Adyen.

​

2 · Frame the redeem URL, not the authorize URL

Mint the buyer session server-side (Bring your own auth), then use the redeemPath as the iframe src:

const { redeemPath } = await alyte.buyerSessions.mint({ merchantId, email: user.email });
iframe.src = ALYTE_URL + redeemPath;   // redeem sets the session cookie INSIDE the frame, then forwards

This ordering matters: inside your page, Alyte’s session cookie is third-party. Alyte sets it SameSite=None; Secure; Partitioned for iframe navigations — but only a redeem that happens in the frame puts the session where the framed page can see it. Redeeming in a top-level tab and then framing the authorize URL will not share the session.

​

3 · Listen for completion

The embedded page posts to your window — only to your registered origin:

window.addEventListener('message', (e) => {
  if (e.origin !== ALYTE_ORIGIN) return;                 // always origin-check
  if (e.data?.type !== 'alyte:authorize') return;
  switch (e.data.event) {
    case 'ready':      showFrame(); break;                 // page loaded
    case 'authorized': break;                              // agent ready, purchase still in progress — keep the modal open
    case 'completed':  closeModal(); refreshAgentsUI(); break;
  }
});

​

Message reference

Every message is { type: 'alyte:authorize', merchantId, event, ...fields }.

event	When	Extra fields
ready	The page has loaded inside your frame	—
authorized	The buyer granted a mandate and a purchase intent (?tier=) is still being carried out. The flow is not finished — do not close the modal	agentId, mandateId, capMinor, currency
completed, outcome: 'authorized'	The buyer granted a mandate and there was no purchase intent — the grant was the whole journey	agentId, mandateId, capMinor, currency
completed, outcome: 'purchased'	The agent bought the intended tier now	tierId, agentId, chargeMinor
completed, outcome: 'queued'	The tier was not buyable yet, so a watch was queued under the mandate	tierId, agentId

completed is terminal: close the modal on it. Branch on outcome to decide what to tell the buyer — a queued watch resolves later via the watch.* webhooks.

There is no cancelled event — your modal’s close button owns dismissal — and no error event: failures are shown to the buyer inside the page, and the modal stays open for them to retry or close.

Omit return when embedding. The page’s “Back to the shop” link is a plain navigation; inside a frame it navigates the frame, not your page. Drive dismissal from the completed message instead and leave the return intent parameter off the redeem link.

​

Notes

• Narrow frames: below tablet width the page collapses to the checkout column and hides the “Your agents” tab. That is intended for a buyer mid-purchase; if you want the management view in your embed, give the frame at least 720px.

• Card capture inside the modal: the page’s Stripe Elements iframe runs at one extra frame depth. Validate it once in a staging embed before enabling in production; if your stack misbehaves, fall back to the redirect flow for the add-card step only.

• The redirect flow keeps working unchanged — treat embedding as progressive enhancement.

• Browser support: the partitioned-cookie flow requires a current Chrome/Edge/Firefox/Safari; very old browsers fall back to redirect.