VouchID Widget SDK Guide & Demo

This page demonstrates how to integrate the VouchID Widget SDK into your application. Follow the steps below to get started and see a live demo.

Live SDK Demo

Interact with the VouchID widget below.

Initializing VouchID Widget...

Server-to-Server Flow Demo

Simulate a verification flow without the widget.

Phone Number

Ready to start.

Integration Guide

Follow these steps to integrate the VouchID Widget SDK.

1. Installation

Option A: Script Tag (CDN)

Add the script to your HTML. The SDK will be available as `window.VouchIDWidget`.

<script src="https://your-cdn-url.com/vouchid-widget-sdk/latest/index.js"></script>

Option B: NPM

Install the package using NPM or Yarn.

npm install @vouchid/widget-sdk

2. Usage

A. Add Container Element

Add a `div` to your HTML where the widget will be mounted.

<div id="vouchid-widget-container"></div>

B. Initialize Widget

Create a new instance of `VouchIDWidget` and mount it.

// Import if using NPM
// import VouchIDWidget from '@vouchid/widget-sdk';

const vouchIdWidget = new VouchIDWidget({
  elementId: 'vouchid-widget-container',
  platformKey: 'YOUR_PUBLIC_PLATFORM_KEY',
  // IMPORTANT: This is NOT a redirect URI. 
  // The user is NEVER sent to this address.
  // The SDK uses the ORIGIN of this URI (e.g., 'https://your-app.com') 
  // to securely send the final token to your page via window.postMessage.
  // The path (e.g., /vouchid/callback) is ignored.
  redirectUri: 'https://your-app.com',
  onSuccess: (data) => {
    console.log('VouchID Success!', data);
    // data -> { platformSessionToken: "a-long-secret-string" }
    // This platformSessionToken is ready to be used by your backend.
    // Send this to your backend to establish a user session or get more info.
  },
  onFailure: (error) => {
    console.error('VouchID Failed:', error);
    // error -> { code: "ERROR_CODE", message: "Error message." }
  },
  onClose: () => {
    console.log('Widget was closed by the user.');
  }
});

vouchIdWidget.mount();

3. Configuration Options

elementId (string, required): ID of the HTML element for the widget.
platformKey (string, required): Your public VouchID Platform Key.
redirectUri (string, required): The URI of your application page where the widget is hosted.
This is NOT a redirect target. The user's browser will never be sent to this URI. Instead, the SDK uses this URI's origin (e.g., `https://your-app.com`) as the `targetOrigin` for the `window.postMessage()` call that securely delivers the `platformSessionToken` to your `onSuccess` callback. You do not need a server-side route for this URI.
onSuccess (function, required): Callback for success. Receives `data: { platformSessionToken: string }`.
onFailure (function, required): Callback for errors. Receives `error: { code: string, message: string }`.
onClose (function, required): Callback for when the user closes the widget.

4. Understanding the `platformSessionToken`

The `platformSessionToken` received in the `onSuccess` callback is the **VouchID platform-specific session token**. It's a ready-to-use Bearer token for your backend to make authenticated calls to VouchID APIs. It is NOT an OAuth authorization code that requires a separate token exchange step.

Send this `platformSessionToken` to your platform's backend.
Your backend can then use this token in an `Authorization: Bearer <token>` header to call VouchID's API (e.g., `/api/user-session` or a similar endpoint) to validate the session and retrieve the `scopedVid` and other relevant, non-PII user metadata associated with your platform.

This example page demonstrates calling a local API route (`/api/platform-actions/get-user-info`) which then securely calls the VouchID backend to retrieve user information using this token.