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. We strongly recommend upgrading - contact your Incode Representative for upgrade information.

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. Pass `true` (or `{}`) for the default scheme, or `{ mgf1: 'sha256' }` when the Incode-provisioned E2EE environment requires it. Not a self-serve flag — E2EE has to be provisioned for your account, and Incode will give you a dedicated `apiURL` (E2EE traffic is served from a different host than the regular API) plus the `mgf1` scheme that environment expects. Pointing `encryption: true` at the standard `apiURL` will fail the handshake. Confirm both values with your Incode account team before enabling. Locked at boot: the first `setup()` call decides both whether encryption is on and which `mgf1` scheme is used. Subsequent `setup()` calls that would change either throw (call `reset()` first). Requires the binary (WASM) transport — `setup({ wasm: false, encryption: true })` throws. See WASM Configuration → End-to-end encryption.
`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>`