Web SDK

@thirdfactor/web opens the hosted verification flow in a popup, a cross-origin modal iframe, or a full-page redirect, listens to the flow over the shared bridge, and resolves a single typed VerificationResult. It is a thin shell: your backend creates the session and gets a hosted url; the browser hands that url to the SDK.

Requirements

Installation

npm install @thirdfactor/web

The package has two entry points, deliberately separated so your browser bundle never imports anything that touches your API key:

import { ThirdFactor } from "@thirdfactor/web";          // browser
import { createSession } from "@thirdfactor/web/server"; // server only

Quick start

// server-side (Node 18+)
import { createSession } from "@thirdfactor/web/server";

const session = await createSession(
  { baseUrl: process.env.TF_BASE_URL!, apiKey: process.env.TF_API_KEY! },
  {
    vendorData: user.id,                    // your reference for this user
    callbackUrl: "https://app.acme.com/kyc/done",
    contactEmail: user.email,
    prefill: { full_name: user.name },
    idempotencyKey: `kyc-${user.id}`,       // safe retries, never double-charged
  },
);
// send { url: session.url, id: session.id } to the browser

import { ThirdFactor } from "@thirdfactor/web";

button.addEventListener("click", async () => {
  const result = await ThirdFactor.verify({
    url: session.url,               // from step 1
    mode: "auto",                   // default; resolves to popup
    onEvent: (e) => console.log(e.type), // ready | completed | error | close
  });

  switch (result.status) {
    case "approved":  showSuccess(); break;   // then confirm server-side
    case "declined":  showFailure(); break;
    case "in_review": showPending(); break;
    case "cancelled": break;                  // user closed the flow
    case "error":     showError(result.error); break;
  }
});

Presentation modes

API reference

ThirdFactor.verify(options): Promise<VerificationResult>

Never rejects — always resolves a VerificationResult.

ThirdFactor.redirect(url: string): void

Full-page navigation to the flow. Does not return. The flow returns the user to the session's callback_url on completion; read the decision from your backend on that return page. Best camera compatibility.

VerificationResult

interface VerificationResult {
  status: "approved" | "declined" | "in_review" | "cancelled" | "error";
  sessionId?: string;                          // echoed from the flow when available
  error?: { code: string; message: string };  // present only when status === "error"
  rawStatus?: string;                          // raw server status (e.g. "abandoned")
}

VerificationEvent

The low-level, per-message stream passed to onEvent. One VerificationResult is still resolved separately once the surface settles.

type VerificationEvent =
  | { type: "ready" }
  | { type: "completed"; status: string; sessionId?: string }
  | { type: "error"; code: string; message?: string }
  | { type: "close" };

Complete API reference

Every exported symbol from @thirdfactor/web and @thirdfactor/web/server, verified against sdks/web/src/:

The server helper: createSession(config, input)

@thirdfactor/web/server wraps POST /v3/session/ so you don't hand-roll the request. It runs only on your server.

• config: { baseUrl, apiKey, fetchImpl? }
• input (all fields optional):

The helper returns the session object ({ id, url, status, decision, expiresAt, ... }). On a non-2xx response it throws ThirdFactorApiError with .status and a stable .code (e.g. insufficient_credits).

Enabling modal (cross-origin iframe)

modal embeds the flow in an iframe on your origin. For that to work, the flow deployment must allowlist your app origin — otherwise the browser refuses the frame (X-Frame-Options) and denies the iframe camera (Permissions-Policy). On the Obsidian flow deployment set:

FLOW_EMBED_ORIGINS="https://app.acme.com https://staging.acme.com"

This adds your origins to the flow route's frame-ancestors and grants them camera/microphone. Every other route keeps X-Frame-Options: DENY. With FLOW_EMBED_ORIGINS unset (the default), cross-origin modal is refused by design — use auto (popup) or redirect.

Error handling

status === "error" carries a stable error.code — branch on it, never on error.message:

const result = await ThirdFactor.verify({ url: session.url });
if (result.status === "error") {
  if (result.error?.code === "expired") reMintSession();
  else showError(result.error);
}

Language, prefill, and metadata

The hosted flow's language, copy, prefill, and workflow are chosen at session-create time, not in the browser SDK:

• Locale — pass locale to createSession (or "locale" in the raw POST /v3/session/ body). The SDK renders whatever the flow serves; no per-platform i18n code.
• Prefill — pass prefill to pre-populate the flow (full_name, first_name, last_name, display_name, date_of_birth, email, phone, nationality, address_line1/2, city, state, country, zip_code). Unknown keys are ignored.
• Your reference — vendorData becomes the session's external reference and the linked identity's external_user_id; it comes back on the session and every webhook.

Browser-side advanced knobs are just expectedOrigin (proxy override) and autoClose.

NFC on the web

The web SDK has no NFC module. Reading an ePassport / eID chip requires the device NFC radio, which a browser cannot reach. When a workflow includes an NFC_VERIFICATION step, the web host advertises no nfc capability, so the flow's server-side fallback applies (the NFC step resolves to manual review). NFC is a native-only capability — see the NFC deep-dive and the iOS, Android, and Flutter SDKs.

How it works

verify() opens the hosted flow with ?embed=1&sdk=web appended. In embed mode the flow reports lifecycle over postMessage instead of redirecting. The SDK validates every message against the flow's origin and the thirdfactor source tag before acting. The same bridge protocol backs the Flutter, iOS, and Android SDKs — see the bridge protocol.

Full end-to-end example

A complete Next.js-style integration: a server route that mints the session, and a client component that opens it and reports the result.

// Runs ONLY on the server — imports @thirdfactor/web/server, which never
// ships to the browser bundle.
import { createSession, ThirdFactorApiError } from "@thirdfactor/web/server";

export async function createKycSession(userId: string, email: string) {
  try {
    const session = await createSession(
      {
        baseUrl: process.env.TF_BASE_URL!,
        apiKey: process.env.TF_API_KEY!,
      },
      {
        vendorData: userId,
        callbackUrl: `${process.env.APP_URL}/kyc/done`,
        contactEmail: email,
        expiresInHours: 24,
        prefill: { email },
        idempotencyKey: `kyc-${userId}`,
      },
    );
    return { url: session.url, id: session.id };
  } catch (err) {
    if (err instanceof ThirdFactorApiError) {
      // e.g. err.code === "insufficient_credits"
      throw new Error(`Could not start verification: ${err.code}`);
    }
    throw err;
  }
}

"use client";

import { useState } from "react";
import { ThirdFactor, type VerificationResult } from "@thirdfactor/web";

export function VerifyButton({ userId }: { userId: string }) {
  const [status, setStatus] = useState<VerificationResult["status"] | "idle">("idle");

  async function handleClick() {
    // Fetch the session URL from YOUR API, which calls createKycSession()
    // server-side. Never call createSession() from the browser.
    const res = await fetch("/api/kyc/session", { method: "POST" });
    const { url } = await res.json();

    const result = await ThirdFactor.verify({
      url,
      mode: "auto",
      onEvent: (e) => console.log("[kyc]", e.type),
    });

    setStatus(result.status);

    switch (result.status) {
      case "approved":
        // UX only — the page can now show a "verified, pending confirmation"
        // state. Grant real access once your backend's webhook handler flips
        // the user's server-side status.
        break;
      case "declined":
        break;
      case "in_review":
        break;
      case "cancelled":
        break;
      case "error":
        if (result.error?.code === "expired") {
          // re-fetch a fresh session URL and let the user retry
        }
        console.error(result.error);
        break;
    }
  }

  return (
    <button onClick={handleClick} disabled={status === "approved"}>
      {status === "idle" ? "Verify identity" : `Status: ${status}`}
    </button>
  );
}

Troubleshooting

FAQ

Related