Web SDK 2.0 API Reference

📘

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation here. Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade.

Full rollout to all clients still TBD.

Setup

setup()

Initialize the SDK before using any components:

TypeScript

import { setup } from '@incodetech/core';

await setup({
  apiURL: string;                                      // Required: API base URL
  token?: string;                                      // Optional: session token (one-shot convenience — delegates to initializeSession)
  customHeaders?: Record<string, string>;
  timeout?: number;                                    // Request timeout (ms)
  wasm?: WasmConfig | false;                           // WASM warmup (see WASM Configuration)
  encryption?: boolean | { mgf1?: 'sha1' | 'sha256' }; // End-to-end encryption (locked at boot)
  hostingApp?: string;                                 // Optional fingerprint hosting-app identifier
  ipLookup?: boolean;                                  // Default true. Set false to skip the third-party IP lookup (api.ipify.org).
  fingerprint?: boolean;                               // Default true. Set false to skip device-fingerprint submission (transition flag).
  devMode?: boolean;                                   // Default false. Set true in local development to silence the devtools detector.
  tri?: { token: string; apiURL: string; autostart?: boolean }; // Optional TRI telemetry config
});

The canonical activation pattern is two calls — setup({ apiURL }) first, then initializeSession({ token }) once the session token is known. See initializeSession() below. Passing token to setup is a one-shot convenience that delegates to initializeSession internally.

Option Type Required Description
apiURL string ❌ API base URL. Omit when every API actor is overridden via .provide() (advanced).
token string ❌ Session token. One-shot convenience that delegates to initializeSession({ token, hostingApp }). Prefer the explicit two-call form: setup({ apiURL }) then initializeSession({ token }). The two-call form lets you start setup (including WASM warmup) before the token is known.
customHeaders Record<string, string> ❌ Headers to attach to every SDK request.
timeout number ❌ Request timeout in milliseconds.
wasm `WasmConfig false` ❌
encryption `boolean { mgf1?: 'sha1' 'sha256' }`
hostingApp string ❌ Hosting app identifier forwarded to the fingerprinting service.
ipLookup boolean ❌ Controls the third-party public-IP lookup (api.ipify.org). Default true (lookup enabled). Set false to opt out — no external call to ipify, at the cost of a less-precise fingerprint. Privacy-friendly for deployments where outbound calls to third-party services are restricted.
fingerprint boolean ❌ Controls client-side device-fingerprint submission (POST /omni/add/device-fingerprint). Default true. Set false to skip it entirely — also blanks the fingerprint hash captured during selfie/ID/authentication verification. Transition flag: with fingerprint: false, the SDK does not auto-inject the mandatory-consent step in flow/workflow (no regulation data to base it on) — handle consent yourself if this applies to your integration.
devMode boolean ❌ Disables the browser devtools detector for local development. Default false. Set true only during local development — the detector feeds an anti-fraud signal and must stay on in production. Do not ship devMode: true. WASM console logging is a separate flag (wasm.showLogs). See WASM Configuration.
tri { token: string; apiURL: string; autostart?: boolean } ❌ Transactional Risk Intelligence (TRI) telemetry. Provide token (a short-lived SDK token from createTRISession, not the org API key) and apiURL (the TRI ingest endpoint). TRI starts automatically unless autostart: false — use false to defer collection until after a consent gate, then call startTRI() from @incodetech/core/tri. Omitting this field opts out; no collectors start.

createSession()

Create a verification session (call from your backend for production):

TypeScript

import { createSession } from '@incodetech/core/session';

const session = await createSession(apiKey, {
  configurationId: string;   // Required: Flow configuration ID from dashboard
  language?: string;         // Optional: Language code (e.g., 'en-US')
  externalId?: string;       // Optional: Your user reference ID
});

// Returns: { token: string; interviewId: string; ... }

initializeSession()

Activate a session by attaching the token to the HTTP client and pre-loading session-scoped state (feature flags, device fingerprint, analytics flush). Call once you have a session token — typically right after createSession() (or after your backend returns the token).

TypeScript

import { initializeSession } from '@incodetech/core/session';

await initializeSession({
  token: string;            // Required in application code: the session token from createSession()
  hostingApp?: string;      // Optional: hosting-app identifier forwarded to fingerprinting
  signal?: AbortSignal;     // Optional: abort the activation (e.g. on unmount)
});

// Returns: { features, disableIpify, fingerprintSuccess, fingerprintResult }
Option Type Required Description
token string ✅ Session token returned by createSession(). Application code should always pass this explicitly.
hostingApp string ❌ Hosting-app identifier forwarded to the fingerprinting service.
signal AbortSignal ❌ Cancellation signal — useful for unmount-aborts in single-page apps.

Results are cached per token: calling initializeSession again with the same token is a no-op; calling with a different token resets the cache and re-initializes from scratch. Idempotent across concurrent callers — a second in-flight call with the same arguments awaits the first.

Components

<incode-flow>

Complete verification flow as a standard Web Component.

TypeScript

// Side-effect import registers the custom element
import '@incodetech/web/flow';
import '@incodetech/web/flow/styles.css';
Property Type Required Description
config FlowConfig ✅ Flow configuration object
onFinish (result?: FinishStatus) => void ✅ Called when flow completes
onError `(error: string undefined, errorCode?: number) => void` ❌

FlowConfig

apiURL is configured via setup(), not in FlowConfig.

Property Type Required Description
token string ✅ Session token from createSession() (token-based variant)
apiKey (or clientId)
+ configurationId string ✅ (alt) Self-loading variant — component creates its own session. Avoid in production.
lang string ❌ Language code (e.g. 'en-US')
enableHome boolean ❌ Show the SDK's built-in home screen
authHint string ❌ QR/auth hint when re-entering a flow
urlUuid string ❌ QR anti-phishing token from URL
wasmConfig WasmConfig ❌ WASM configuration for ML features
spinnerConfig SpinnerConfig ❌ Loading spinner customization
disableDashboardTheme boolean ❌ Disable dashboard theme
onFlowEvent (event: FlowEvent) => void ❌ Curated flow milestones
onModuleLoading (moduleKey: string) => void ❌ Called when module starts loading
onModuleLoaded (moduleKey: string) => void ❌ Called when module finishes loading
onWasmWarmup (pipelines: string[]) => void ❌ Called when WASM warmup begins
onUrlUuidRefreshed (urlUuid: string) => void ❌ New urlUuid available

Other components

The SDK ships 20+ web components in addition to IncodeFlow — selfie, ID capture, phone, email, signature, consent, eKYC/eKYB orchestrators, and more. Rather than duplicate them here, see:

Headless Managers

Every module ships a corresponding createXxxManager factory for headless integrations. The full catalog (manager name, core import, what it does) lives in Individual Modules; detailed lifecycle, state, and method documentation for each manager lives in Headless Mode.

For the four most-used headless APIs, see: