Web SDK 2.0 API Reference

Setup

setup()

Initialize the SDK before using any components:

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
});

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`	❌	WASM warmup. Omit to skip preload (loads lazily on first selfie/ID capture). Pass an object to warm up with CDN defaults plus any overrides. Pass `false` to explicitly disable. See WASM Configuration.
`encryption`	`boolean \| { mgf1?: 'sha1' \| 'sha256' }`	❌	Enable end-to-end encryption for SDK traffic. Independent of `token` — can be enabled before a session token is known. Not a self-serve flag — your Incode account team provisions the environment and gives you the dedicated `apiURL` and `mgf1` scheme. Locked at boot (call `reset()` to change later) and requires the WASM binary transport. See End-to-End Encryption for the full walkthrough including API-key transmission, MGF1 schemes, and failure modes.
`hostingApp`	`string`	❌	Hosting app identifier forwarded to the fingerprinting service.

createSession()

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

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).

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.

// 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`	❌	Called when an error occurs

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:

Individual Modules — complete catalog of every web component and headless manager with import paths
Web Components — tag-table reference for vanilla / framework-agnostic usage
Module: Selfie, Module: ID, Module: Phone, Module: Email — deep-dive reference pages for the four most-used capture modules, including config tables, state machines, and full API surfaces

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:

Module: Selfie § API Methods
Module: ID § API Methods
Module: Phone § API Methods
Module: Email § API Methods