Iframe integration

The iframe is a self-contained verification UI hosted on the platform domain. Your frontend embeds it and listens to postMessage events for real-time updates.

Embedding

<iframe
  src="https://iframe.kyve.dev?session_id=ses_...&token=..."
  allow="camera; microphone"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
  style="width: 100%; min-height: 560px; border: 0"
></iframe>

The session_id and token come from POST /v1/sessions. Both are required — the iframe will refuse to initialize without them.

Event envelope

Every postMessage event uses a fixed envelope:

interface IframeEventEnvelope {
  type: string;           // e.g. "kyc.completed"
  version: 1;             // protocol version
  session_id: string;
  livemode: boolean;
  emitted_at: string;     // ISO 8601
  data: unknown;          // type-specific payload
}

Event types

Type	When it fires
`kyc.ready`	Iframe has initialized and validated the SDK token.
`kyc.status_changed`	A step advances (`document_upload` → `liveness`, etc.).
`kyc.resize`	Iframe content height changed — adjust your host element.
`kyc.completed`	Terminal success. The verification is saved.
`kyc.error`	Terminal failure with a machine-readable `code`.
`kyc.canceled`	User or parent aborted the flow.

Always validate `event.origin`

Only accept messages whose origin matches your configured iframe origin. Drop everything else.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://iframe.kyve.dev') return;
  const envelope = event.data as IframeEventEnvelope;
  if (envelope?.version !== 1) return;
  // ...handle event
});

Parent → iframe commands

You can send commands to the iframe from the parent window:

kyc.configure — set theme (light / dark) and locale.
kyc.cancel — cancel the current flow cleanly.

Session resume after a page refresh is automatic — the iframe fetches the current snapshot on initialization and renders the correct screen. There is no explicit resume command.

All commands use the same envelope shape as iframe → parent events.