Redirect & iFrame

Redirect users to iDenfy or embed the identity verification flow in your web page via iFrame with customizable query parameter options.

After creating a verification session, you need to send your user to the iDenfy verification UI. There are two approaches: embed an iFrame directly in your page, or redirect your user to an iDenfy-hosted page.

---

iFrame Integration

Embedding the verification flow in an iFrame keeps users on your site and gives you full control over the experience.

Base URL

https://ui.idenfy.com/

Query Parameters

Parameter	Required	Description
authToken	Yes	The verification token returned by the session creation endpoint.
lang	No	Forces the UI into a specific language (e.g. en, lt, de). If omitted, the user can choose.

Sizing Recommendations

On desktop, use the recommended 670 × 800 px embed size so all verification steps display without internal scrolling — cramped heights cause scrolling at the camera step, which is where users drop. This is a guideline, not a hard minimum. On mobile (below the 575px breakpoint), switch to 100% width and 100% height so the iFrame fills the viewport — this gives the best experience for camera capture and liveness checks.

The UI adapts across three layouts, based on the iFrame’s width:

Breakpoint	Layout
≤ 575px	Full mobile
576px – 991px	Mixed-card
≥ 992px	Full desktop

Aim for the full desktop (≥ 992px) or full mobile (≤ 575px) layout — the mixed-card middle works, it just isn’t the richest UI.

Required Attributes

You must add the allow="camera; fullscreen; clipboard-write" and allowfullscreen attributes to the iFrame element. Camera access is required for document capture, and fullscreen is required for 3D liveness detection. Without them, the camera-based checks will fail.

<iframe
  allow="camera; fullscreen; clipboard-write"
  allowfullscreen
></iframe>

Embedding something other than https://ui.idenfy.com? If your iFrame src is the redirect URL (https://ivs.idenfy.com/api/v2/redirect?...) or a custom UI domain, name the final UI origin in the allow list:

allow="camera https://ui.idenfy.com; fullscreen https://ui.idenfy.com; clipboard-write https://ui.idenfy.com"

The default allowlist only covers the iFrame’s own src origin, so permissions are lost after the cross-origin redirect. With a custom UI domain, use that domain here and in the message origin check below.

Skip the sandbox attribute. Bank verification and Digital ID flows open popups, and sandboxing blocks them. If your security policy requires it, include at least:

sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"

allow-popups lets the popup open; allow-popups-to-escape-sandbox keeps the identity provider’s login page working.

Listening for Verification Results

When the verification session ends, the iFrame posts a message event to the parent window. You must listen for this event to know the outcome.

window.addEventListener("message", function (event) {
  // Verify the origin for security
  if (event.origin !== "https://ui.idenfy.com") return;

  // Native WebViews and some proxies stringify the payload — handle both forms
  let data = event.data;
  if (typeof data === "string") {
    try { data = JSON.parse(data); } catch { return; }
  }
  if (!data || typeof data !== "object") return;

  console.log("Status:", data.status);
  console.log("Manual status:", data.manualStatus);
  console.log("Auto suspected:", data.autoSuspected);
  console.log("Manual suspected:", data.manualSuspected);
});

Message Event Fields

Field	Type	Description
status	string	Automatic review result: approved, failed, or unverified.
manualStatus	string	Manual (human) review result: approved, failed, or waiting.
autoSuspected	boolean	true if the automatic check flagged the verification as suspicious.
manualSuspected	boolean	true if a human reviewer flagged the verification as suspicious.

All status values are delivered lowercase. manualStatus will be waiting immediately after the session completes — the final manual review result is delivered asynchronously via webhook. Do not treat waiting — or an unverified status — as a final state.

Do not set successUrl, errorUrl, or unverifiedUrl when using the iFrame integration. These parameters cause the iFrame to redirect internally, which breaks the embedded flow. Use the message event instead to handle outcomes.

Full HTML Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <style>
    #idenfy-iframe { border: none; width: 670px; height: 800px; }
    @media (max-width: 575px) {
      #idenfy-iframe { width: 100%; height: 100vh; }
    }
  </style>
</head>
<body>
  <!-- See "Required Attributes" above before changing the allow list or adding a sandbox attribute -->
  <iframe id="idenfy-iframe" allow="camera; fullscreen; clipboard-write" allowfullscreen
    src="https://ui.idenfy.com/?authToken=YOUR_TOKEN"></iframe>
  <script>
    window.addEventListener("message", (e) => {
      if (e.origin !== "https://ui.idenfy.com") return;
      let data = e.data;
      if (typeof data === "string") {
        try { data = JSON.parse(data); } catch { return; }
      }
      if (!data || typeof data !== "object") return;

      if (data.status === "approved") {
        // Automatic check passed — show success state
      } else if (data.status === "failed") {
        // Automatic check failed — show failure state
      } else if (data.status === "unverified") {
        // Could not determine automatically — wait for manual review
      }
      // Always check manualStatus via webhook for the final result
    });
  </script>
</body>
</html>

---

Redirect Integration

If you prefer a simpler integration without iFrame embedding, redirect your user to the iDenfy verification page. Your user leaves your site, completes verification, and returns to your redirect URL.

Redirect URL

https://ivs.idenfy.com/api/v2/redirect?authToken={authToken}

Replace {authToken} with the token from the session creation endpoint.

When using redirect, you can configure successUrl, errorUrl, and unverifiedUrl during session creation. iDenfy will redirect the user back to the appropriate URL after the session ends.

---

Why There Is No Web SDK

iDenfy intentionally does not provide a JavaScript Web SDK. The iFrame approach is the recommended integration for web applications.

Benefits of the iFrame-only approach:

• Always up to date — your integration automatically uses the latest UI, liveness detection, and document recognition without any code changes on your side.
• Lighter integration — no package to install, no bundle size impact, no dependency management.
• Future-proof — new features, supported documents, and UX improvements are available immediately.
• No version management — you never need to track SDK releases or handle breaking changes.

---

Next Steps

Set up webhooks

Receive real-time verification results on your server.

Mobile SDKs

Native Android and iOS SDKs for mobile apps.