Web SDK 2.0 API Reference

Initialize the SDK before using any components:

📘
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:

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:

Setup

setup()

createSession()

initializeSession()

Components

<incode-flow>

FlowConfig

Other components

Headless Managers

See Also

`<incode-flow>`