Iframe Identity Verification: Embedded Web KYC

Embed the Didit verification flow directly within your application using an iframe. This provides a seamless experience without redirecting users away from your site.

Overview

Feature	UniLink (No Backend)	API Session (With Backend)
Setup Time	< 1 minute	5-10 minutes
Backend Required	❌ No	✅ Yes
Custom `vendor_data`	❌ No	✅ Yes
Custom `metadata`	❌ No	✅ Yes
Per-session Callback	❌ No	✅ Yes
Session Tracking	❌ No	✅ Yes

UniLink Iframe (No Backend Required)

The fastest way to get started – just copy and paste your UniLink URL.

What You Need

A Didit workflow (created in the Didit Console)
Your UniLink URL (click Copy Link on your workflow)

Implementation

<iframe 
  src="https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64"
  style="width: 100%; height: 700px; border: none;" 
  allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
></iframe>

⚠️ Required: The allow attribute is mandatory for camera access during liveness detection.

Key Benefits

Less than 1 minute setup — No backend, no API keys
Zero configuration — Callback URL set in workflow settings
Ideal for MVPs — Get started immediately

API Session Iframe (With Backend)

For advanced integrations that need per-session customization.

When to Use

Pass custom vendor_data or metadata per session
Set different callback URLs per session
Track sessions server-side before verification starts
Associate sessions with your user IDs

Implementation

Step 1: Create a session (backend) The session-create response uses a field named url — use that as the iframe src.

// Node.js / Express
app.post('/api/create-verification', async (req, res) => {
  const { userId } = req.body;

  const response = await fetch('https://verification.didit.me/v3/session/', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DIDIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: userId,
      callback: 'https://yourapp.com/verification-callback',
      metadata: { source: 'web-app', timestamp: Date.now() },
    }),
  });

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  // 201 per OpenAPI: { session_id, session_number, session_token, url, vendor_data,
  //                    metadata, status, workflow_id, workflow_version, callback }
  const session = await response.json();
  res.json({ sessionId: session.session_id, verificationUrl: session.url });
});

Step 2: Embed in iframe (frontend)

<iframe 
  id="didit-verification"
  src="" <!-- Set dynamically from API response -->
  style="width: 100%; height: 650px; border: none;" 
  allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
></iframe>

<script>
  async function startVerification() {
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    document.getElementById('didit-verification').src = verificationUrl;
  }
</script>

Listening for Events (postMessage)

The verification page posts events to the parent window. Every message has this envelope:

{
  type: 'didit:<event>',   // e.g. 'didit:completed'
  data: { /* payload */ }, // event-specific; may be undefined
  timestamp: 1718000000000 // ms epoch
}

The payload is nested — read event.data.data.sessionId, not event.data.sessionId:

window.addEventListener('message', (event) => {
  // Use your white-label domain here if you have one configured
  if (event.origin !== 'https://verify.didit.me') return;

  const { type, data } = event.data || {};

  if (type === 'didit:ready') {
    console.log('Session ID:', data.sessionId); // available as soon as the page loads
  }
  if (type === 'didit:completed') {
    console.log('Done:', data.sessionId, data.status); // e.g. "Approved" | "Declined" | "In Review"
    // UI hint only — the canonical decision arrives on your backend via webhook
  }
});

Key events: didit:ready ({ sessionId }), didit:started, didit:step_started / didit:step_completed / didit:step_changed ({ step, ... }), didit:status_updated ({ status }), didit:completed ({ sessionId, status }), didit:cancelled, didit:error ({ error, step? }), didit:close_request, and didit:layout ({ contentHeight, colorScheme, dir }, see below). The JavaScript SDK event reference lists the verification events available as typed callbacks. From version 0.5.0, the SDK handles layout messages internally rather than forwarding them to onEvent.

Size the iframe from `didit:layout`

The verification page tells you how much room it needs with a didit:layout message. It sends one when it loads and another whenever its content height, theme or text direction changes:

{
  type: 'didit:layout',
  data: {
    contentHeight: 612,    // CSS px
    colorScheme: 'light',  // 'light' | 'dark'
    dir: 'ltr'             // 'ltr' | 'rtl'
  },
  timestamp: 1718000000000
}

Field	Type	Description
`contentHeight`	`number`	The natural height of the page’s content in CSS pixels, top bar included
`colorScheme`	`'light' \| 'dark'`	The theme the page is shown in. With white-label colors, your background color decides it, not the device setting
`dir`	`'ltr' \| 'rtl'`	The text direction of the page’s language

To receive didit:layout in your own iframe, add sdk_presentation=embedded to its verification URL. From version 0.5.0, the JavaScript SDK sets the presentation for you. Without a presentation parameter, the page uses its standalone layout and does not send layout messages.

This host follows the recommended sizes: a fixed card from 1024px wide, full screen at 540px and below, and in between an iframe 500px wide that takes the height the page reports:

<iframe
  id="didit-verification"
  class="didit-iframe"
  title="Didit verification"
  allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
></iframe>

<style>
  /* 541px to 1023px wide: 500px wide and as tall as the content */
  .didit-iframe {
    display: block;
    width: 500px;
    max-width: 100%;
    height: var(--didit-content-height, 700px); /* 700px until the first didit:layout */
    max-height: 90vh;
    max-height: 90dvh;
    margin: 0 auto;
    border: none;
    border-radius: 16px;
  }

  /* 1024px and wider: the computer card */
  @media (min-width: 1024px) {
    .didit-iframe {
      width: 960px;
      max-width: 90vw;
      height: 660px;
    }
  }

  /* 540px and below: full screen */
  @media (max-width: 540px) {
    .didit-iframe {
      position: fixed;
      inset: 0;
      width: 100%;
      height: 100vh;
      height: 100dvh;
      max-height: none;
      border-radius: 0;
    }
  }
</style>

<script>
  const DIDIT_ORIGIN = 'https://verify.didit.me'; // or your white-label domain
  const iframe = document.getElementById('didit-verification');

  // verificationUrl: the session `url` from your backend, or your UniLink
  const src = new URL(verificationUrl);
  src.searchParams.set('sdk_presentation', 'embedded');
  window.addEventListener('message', (event) => {
    if (event.origin !== DIDIT_ORIGIN || event.source !== iframe.contentWindow) return;
    const { type, data } = event.data || {};
    if (type !== 'didit:layout') return;
    const height = data?.contentHeight;
    if (typeof height !== 'number' || !Number.isFinite(height) || height <= 0) return;

    // Only the 541px to 1023px size reads it; the other two sizes are fixed
    iframe.style.setProperty('--didit-content-height', `${height}px`);
  });
  iframe.src = src.toString();
</script>

Between 541px and 1023px, this example uses a 700px starting height until a layout message arrives, capped at 90% of the visible window height. The computer and phone sizes apply immediately. On phones the iframe covers the window, so provide a way to leave verification in your host. Use colorScheme and dir to match any controls you draw around the iframe to the page’s theme and text direction. If the user’s connection drops, the page shows a “No internet connection” screen that closes by itself once the connection is back. If the user chooses Exit Verification there, the page sends didit:error with error: "network_error", then didit:cancelled: close the iframe on didit:cancelled.

For a polished modal experience that overlays your page:

HTML/CSS/JS

<!DOCTYPE html>
<html>
<head>
  <style>
    .didit-modal-overlay {
      display: none;
      position: fixed;
      inset: 0;
      background: rgba(0, 0, 0, 0.6);
      z-index: 9999;
      backdrop-filter: blur(4px);
    }
    
    .didit-modal-container {
      position: absolute;
      top: 50%;
      left: 50%;
      transform: translate(-50%, -50%);
      width: 90%;
      max-width: 480px;
      height: 85vh;
      max-height: 750px;
      background: white;
      border-radius: 16px;
      overflow: hidden;
      box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
    }
    
    .didit-modal-close {
      position: absolute;
      top: 12px;
      right: 12px;
      z-index: 10;
      width: 32px;
      height: 32px;
      border: none;
      background: rgba(0, 0, 0, 0.1);
      border-radius: 50%;
      cursor: pointer;
      font-size: 18px;
      display: flex;
      align-items: center;
      justify-content: center;
    }
    
    .didit-modal-close:hover {
      background: rgba(0, 0, 0, 0.2);
    }
    
    .didit-iframe {
      width: 100%;
      height: 100%;
      border: none;
    }
  </style>
</head>
<body>
  <button onclick="openVerification()">Verify Identity</button>

  <div id="didit-modal" class="didit-modal-overlay">
    <div class="didit-modal-container">
      <button class="didit-modal-close" onclick="closeVerification()">✕</button>
      <iframe 
        id="didit-iframe"
        class="didit-iframe"
        allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
      ></iframe>
    </div>
  </div>

  <script>
    const UNILINK_URL = 'https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64';
    
    function openVerification() {
      document.getElementById('didit-iframe').src = UNILINK_URL;
      document.getElementById('didit-modal').style.display = 'block';
      document.body.style.overflow = 'hidden';
    }
    
    function closeVerification() {
      document.getElementById('didit-iframe').src = '';
      document.getElementById('didit-modal').style.display = 'none';
      document.body.style.overflow = '';
    }
    
    // Close on escape key
    document.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') closeVerification();
    });
    
    // Close on overlay click
    document.getElementById('didit-modal').addEventListener('click', (e) => {
      if (e.target.id === 'didit-modal') closeVerification();
    });
  </script>
</body>
</html>

React Component

A reusable React component for modal-based verification:

import { useState, useEffect } from 'react';

interface DiditInContextProps {
  /**
   * Either the `url` returned by POST /v3/session/ (API session)
   * or your UniLink URL copied from the Console (Workflows → Copy Link).
   * Don't derive the UniLink yourself — the path segment is a 22-character
   * base64url encoding of the workflow UUID's raw bytes, not btoa(workflowId).
   */
  verificationUrl: string;
  isOpen: boolean;
  onClose: () => void;
  onComplete?: (sessionId: string, status: string) => void;
}

export function DiditInContext({ 
  verificationUrl, 
  isOpen, 
  onClose,
  onComplete 
}: DiditInContextProps) {
  const [iframeSrc, setIframeSrc] = useState<string>('');

  useEffect(() => {
    if (isOpen) {
      setIframeSrc(verificationUrl);
      document.body.style.overflow = 'hidden';
    } else {
      setIframeSrc('');
      document.body.style.overflow = '';
    }
  }, [isOpen, verificationUrl]);

  // Listen for postMessage from iframe
  // Messages look like: { type: 'didit:<event>', data: {...}, timestamp }
  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      // Use your white-label domain here if you have one configured
      if (event.origin !== 'https://verify.didit.me') return;

      if (event.data?.type === 'didit:completed' && onComplete) {
        onComplete(event.data.data?.sessionId, event.data.data?.status);
        onClose();
      }
    };

    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, [onComplete, onClose]);

  // Handle escape key
  useEffect(() => {
    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === 'Escape' && isOpen) onClose();
    };
    
    document.addEventListener('keydown', handleEscape);
    return () => document.removeEventListener('keydown', handleEscape);
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return (
    <div 
      className="fixed inset-0 bg-black/60 backdrop-blur-sm z-50 flex items-center justify-center"
      onClick={(e) => e.target === e.currentTarget && onClose()}
    >
      <div className="relative w-[90%] max-w-[480px] h-[85vh] max-h-[750px] bg-white rounded-2xl overflow-hidden shadow-2xl">
        <button 
          onClick={onClose}
          className="absolute top-3 right-3 z-10 w-8 h-8 rounded-full bg-black/10 hover:bg-black/20 flex items-center justify-center"
          aria-label="Close"
        >
          ✕
        </button>
        <iframe 
          src={iframeSrc}
          className="w-full h-full border-0"
          allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
          title="Didit Verification"
        />
      </div>
    </div>
  );
}

Usage

import { useState } from 'react';
import { DiditInContext } from './DiditInContext';

function App() {
  const [isVerificationOpen, setIsVerificationOpen] = useState(false);
  
  return (
    <>
      <button onClick={() => setIsVerificationOpen(true)}>
        Verify Identity
      </button>
      
      <DiditInContext
        verificationUrl="https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64" // UniLink from Console, or the API session `url`
        isOpen={isVerificationOpen}
        onClose={() => setIsVerificationOpen(false)}
        onComplete={(sessionId, status) => {
          console.log(`Verification ${status}: ${sessionId}`);
          if (status === 'Approved') {
            // Navigate to success page
          }
        }}
      />
    </>
  );
}

Vue Component

<template>
  <Teleport to="body">
    <div 
      v-if="isOpen"
      class="fixed inset-0 bg-black/60 backdrop-blur-sm z-50 flex items-center justify-center"
      @click.self="$emit('close')"
    >
      <div class="relative w-[90%] max-w-[480px] h-[85vh] max-h-[750px] bg-white rounded-2xl overflow-hidden shadow-2xl">
        <button 
          @click="$emit('close')"
          class="absolute top-3 right-3 z-10 w-8 h-8 rounded-full bg-black/10 hover:bg-black/20 flex items-center justify-center"
        >
          ✕
        </button>
        <iframe 
          :src="iframeSrc"
          class="w-full h-full border-0"
          allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"
        />
      </div>
    </div>
  </Teleport>
</template>

<script setup lang="ts">
import { computed, watch, onMounted, onUnmounted } from 'vue';

const props = defineProps<{
  isOpen: boolean;
  // The `url` from POST /v3/session/, or your UniLink URL copied from the
  // Console (Workflows → Copy Link). Don't derive the UniLink with btoa() —
  // its path segment is base64url of the workflow UUID's raw bytes.
  verificationUrl: string;
}>();

const emit = defineEmits<{
  close: [];
  complete: [sessionId: string, status: string];
}>();

const iframeSrc = computed(() => (props.isOpen ? props.verificationUrl : ''));

// Handle escape key
const handleEscape = (e: KeyboardEvent) => {
  if (e.key === 'Escape' && props.isOpen) emit('close');
};

// Handle postMessage — messages look like { type: 'didit:<event>', data: {...}, timestamp }
const handleMessage = (event: MessageEvent) => {
  // Use your white-label domain here if you have one configured
  if (event.origin !== 'https://verify.didit.me') return;
  if (event.data?.type === 'didit:completed') {
    emit('complete', event.data.data?.sessionId, event.data.data?.status);
  }
};

onMounted(() => {
  document.addEventListener('keydown', handleEscape);
  window.addEventListener('message', handleMessage);
});

onUnmounted(() => {
  document.removeEventListener('keydown', handleEscape);
  window.removeEventListener('message', handleMessage);
});

// Lock body scroll when open
watch(() => props.isOpen, (isOpen) => {
  document.body.style.overflow = isOpen ? 'hidden' : '';
});
</script>

Configuration

Required Permissions

Use this full permission list for capture, location, copying and media compatibility:

allow="camera; microphone; geolocation; clipboard-write; fullscreen; autoplay; encrypted-media; digital-credentials-get"

Permission	Used for and what happens without it
`camera`	Document scanning and face capture. Without it, the camera cannot start and the user sees camera-access guidance
`microphone`	Optional audio during document and face video capture. Without it, capture continues without audio
`geolocation`	The location step reads the device’s position. Without it, the user sees Location access is off, even if they allowed location in the browser
`clipboard-write`	Copying the session reference or verification link, including on the in-app browser screen. Without it, the copy action can fail and the user must copy the visible text or browser address manually
`fullscreen`	Lets media controls request full screen. Without it, those controls stay inside the iframe
`autoplay`	Lets instructional videos and camera previews play automatically, subject to browser rules. Without it, playback may wait for a user action
`encrypted-media`	Retained for protected-media compatibility. Current capture steps do not require it; without it, protected-media playback would be blocked
`digital-credentials-get`	Sharing a digital ID from a wallet such as Google Wallet through the browser’s Digital Credentials API. Without it, the browser refuses the wallet request inside your iframe, so the user cannot share an ID from the wallet there

The allow attribute delegates permissions; it does not override the user’s choice or a stricter Permissions-Policy header on your host page.

Iframe size

The verification flow lays itself out for the size of its iframe. Size the iframe for the window it is shown in:

Window width	Recommended iframe size
1024px and wider (computer)	960px by 660px, at most 90% of the window’s width and height. Keep this size in every step
541px to 1023px	500px wide and as tall as the content: take the height from the `contentHeight` of the `didit:layout` message, at most 90% of the window’s height
540px and below (phone)	Full screen: the full width and the full visible height of the window, without rounded corners

For the middle range, start at 500px by 700px until the first didit:layout message arrives, with the same height cap. The didit:layout example applies all three sizes, including the computer and phone sizes before any message arrives.

Content Security Policy (CSP)

If you use CSP, add Didit to your frame-src directive:

Content-Security-Policy: frame-src https://verify.didit.me;

Cross-Device Verification

The InContext iframe automatically supports cross-device verification:

User starts verification on desktop
If camera is unavailable, a QR code is shown
User scans QR code on mobile
User completes verification on mobile
Desktop iframe automatically updates with result

This happens automatically – no additional configuration needed.

Troubleshooting

Camera Not Working

Ensure the iframe includes the full permission list
Check that your site is served over HTTPS
Verify the user has granted camera permissions to your domain
Try the Redirect method if iframe camera access fails

Iframe Not Loading

Check for Content Security Policy (CSP) issues
Add https://verify.didit.me to your frame-src directive
Check browser console for errors

postMessage Not Received

Verify you’re listening for the correct origin (https://verify.didit.me, or your white-label domain)
Check that the event listener is added before opening the iframe
Check the event name and shape: types are prefixed (didit:completed, not verification_complete) and the payload is nested under event.data.data

Example Repository

GitHub Repository

View source code and examples on GitHub

Guides

Authentication

Model Context Protocol (MCP)

Web SDKs

Native SDKs

Server SDKs

Integrations

Iframe Identity Verification: Embedded Web KYC

Overview

UniLink Iframe (No Backend Required)

What You Need

Implementation

Key Benefits

API Session Iframe (With Backend)

When to Use

Implementation

Listening for Events (postMessage)

Size the iframe from `didit:layout`

HTML/CSS/JS

React Component

Usage

Vue Component

Configuration

Required Permissions

Iframe size

Content Security Policy (CSP)

Cross-Device Verification

Troubleshooting

Camera Not Working

Iframe Not Loading

postMessage Not Received

Example Repository

GitHub Repository

Overview

UniLink Iframe (No Backend Required)

What You Need

Implementation

Key Benefits

API Session Iframe (With Backend)

When to Use

Implementation

Listening for Events (postMessage)

Size the iframe from didit:layout

Modal Implementation

HTML/CSS/JS

React Component

Usage

Vue Component

Configuration

Required Permissions

Iframe size

Content Security Policy (CSP)

Cross-Device Verification

Troubleshooting

Camera Not Working

Iframe Not Loading

postMessage Not Received

Example Repository

GitHub Repository

Size the iframe from `didit:layout`