OAuth 2.0

iframe Implementations

Use an iframe implementation when you want users to start and complete an ID.me OAuth 2.0 verification flow without leaving your site. The OAuth parameters, redirect URI, token exchange, and attribute retrieval are the same as a standard OAuth 2.0 Authorization Code integration; the main difference is that the ID.me authorization and verification pages render inside an iframe that you host.

Your iframe parent URL must be approved by ID.me before the embedded flow will load. Send ID.me each exact origin that will host the iframe, including the scheme and host, such as https://www.example.com. Include non-standard ports for test environments, such as https://staging.example.com:8443.

Requirements

Before building your iframe implementation, make sure you have:

  • An existing ID.me OAuth 2.0 application with a configured client_id, redirect_uri, and scope.
  • An HTTPS page that will host the iframe. Production iframe implementations must be served over HTTPS.
  • Each iframe parent origin added to the ID.me iframe-whitelist.
  • A stable state value for CSRF protection and request correlation.
  • PKCE if your application type or security model requires it.

If your site uses a Content Security Policy, allow ID.me pages to load in frames:

CSP example
1Content-Security-Policy: frame-src https://api.id.me https://verify.id.me;

For test environments, use the ID.me test hosts provided by your ID.me contact.

iframe permissions

Verification flows may require camera and microphone access for document capture, selfie capture, or liveness checks. Delegate those browser permissions to the iframe:

iframe permissions
1<iframe
2  title="ID.me verification"
3  src="https://api.id.me/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&scope=YOUR_SCOPE&state=YOUR_STATE&eid=YOUR_EXTERNAL_IDENTIFIER&appID=YOUR_EXTERNAL_APP_ID"
4  allow="camera; microphone; fullscreen"
5  referrerpolicy="strict-origin-when-cross-origin">
6</iframe>

If your application sends a Permissions-Policy header, allow camera and microphone for the ID.me origins used by your integration:

Permissions-Policy example
1Permissions-Policy: camera=(self "https://api.id.me" "https://verify.id.me"), microphone=(self "https://api.id.me" "https://verify.id.me")

Avoid adding a restrictive sandbox attribute unless you have tested every verification step. If your application requires sandboxing, the iframe must still allow scripts, forms, same-origin behavior, popups, and the camera or microphone capabilities required by your verification flow.

Build the iframe page

Start with a normal OAuth 2.0 authorization URL. Replace the placeholder values with your application values:

Authorization URL
https://api.id.me/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
  &response_type=code
  &scope=YOUR_SCOPE
  &state=YOUR_STATE
  &eid=YOUR_EXTERNAL_IDENTIFIER
  &appID=YOUR_EXTERNAL_APP_ID

Then render the authorization URL inside an iframe. The example below renders a “Sign in with ID.me” launcher button inside the iframe first. When the user clicks the button, the iframe navigates to the ID.me authorization URL.

Sample iframe launcher
1<iframe
2  id="idme-verification-iframe"
3  title="ID.me verification"
4  allow="camera; microphone; fullscreen"
5  referrerpolicy="strict-origin-when-cross-origin">
6</iframe>
7
8<script>
9  const authorizeUrl = 'https://api.id.me/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&scope=YOUR_SCOPE&state=YOUR_STATE&eid=YOUR_EXTERNAL_IDENTIFIER&appID=YOUR_EXTERNAL_APP_ID';
10
11  const launcherHtml = `<!doctype html>
12<html lang="en">
13  <head>
14    <meta charset="utf-8">
15    <base target="_self">
16  </head>
17  <body>
18    <a href="${authorizeUrl.replaceAll('&', '&amp;')}">Sign in with ID.me</a>
19  </body>
20</html>`;
21
22  document.getElementById('idme-verification-iframe').srcdoc = launcherHtml;
23</script>

Download sample HTML

Handle redirects

The user still returns to your registered redirect_uri after the ID.me flow completes. Your callback handler should:

  • Validate the state parameter.
  • Exchange the authorization code for tokens using your existing backend OAuth flow.
  • Retrieve user attributes from the ID.me APIs.
  • Render a completion page that works both inside and outside an iframe.

If the callback page is expected to render inside the iframe, make sure your own application does not block that page with X-Frame-Options or a Content-Security-Policy frame-ancestors directive.

Testing checklist

Use this checklist after ID.me confirms your parent origin is on the iframe-whitelist:

  • Open the page from the exact whitelisted origin. https://www.example.com and https://example.com are different origins.
  • Confirm the iframe loads the ID.me authorization page after the user clicks the button.
  • Complete the verification flow in a browser with third-party cookies enabled for the test.
  • Confirm camera and microphone prompts appear when your policy requires document capture, selfie capture, or liveness.
  • Confirm the final redirect reaches your registered redirect_uri and your application validates state.
  • Test on the desktop and mobile browsers you support.
Best practice

Keep a standard redirect implementation available as a fallback. Browser privacy settings, embedded browser restrictions, or customer-specific security headers can prevent any third-party iframe flow from completing even when the iframe-whitelist is configured correctly.