SDK and iframe embeds

SDK behavior

The SDK validates locally, debounces generation by exactly 500 ms, permits one request in flight plus one latest queued state, deduplicates promises, and preserves the last good image on failure. Display and cache hits are not billable requests.

Public iframe

Use /embed/public for anonymous provider-branded previews. It does not use Clerk, third-party cookies, API keys, or browser-session credentials.

Registered iframe

Use /embed/registered behind a same-origin backend proxy that obtains a short-lived browser session with the server-held project key and injects it in the upstream Authorization header. The proxy also forwards the iframe's /api/v1 calls under that same allowed origin.

Do not put credentials in iframe URLs, cookies, browser bundles, or postMessage payloads. The event protocol validates version, source Window, exact origin, and instance ID for ready, change, availability, error, and resize messages.

Options

Availability, visible verification, color editing, selector or fixed shape, retail CTA, initial configuration, and theme are supported. Selector and fixed-shape options are mutually exclusive.