# Web SDK 2.0 API Reference

<WebSDK2 />

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

The canonical activation pattern is two calls — `setup({ apiURL })` first, then `initializeSession({ token })` once the session token is known. See [`initializeSession()`](#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 })`](#initializesession). 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](doc:web-sdk-2-wasm).                                                                                                                                                                                                               |
| `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](doc:web-sdk-2-e2ee) 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):

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

```ts
// 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](doc:web-sdk-2-individual-modules) — complete catalog of every web component and headless manager with import paths
* [Web Components](doc:web-sdk-2-web-components) — tag-table reference for vanilla / framework-agnostic usage
* [Module: Selfie](doc:web-sdk-2-module-selfie-1), [Module: ID](doc:web-sdk-2-module-id-capture), [Module: Phone](doc:web-sdk-2-module-phone), [Module: Email](doc:web-sdk-2-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](doc:web-sdk-2-individual-modules); detailed lifecycle, state, and method documentation for each manager lives in [Headless Mode](doc:web-sdk-2-headless-mode).

For the four most-used headless APIs, see:

* [Module: Selfie § API Methods](doc:web-sdk-2-module-selfie-1#api-methods)
* [Module: ID § API Methods](doc:web-sdk-2-module-id-capture#api-methods)
* [Module: Phone § API Methods](doc:web-sdk-2-module-phone#api-methods)
* [Module: Email § API Methods](doc:web-sdk-2-module-email#api-methods)

## See Also

* [TypeScript Types](doc:web-sdk-2-typescript-types): Type definitions
* [Headless Mode](doc:web-sdk-2-headless-mode): Detailed headless API
* [Individual Modules](doc:web-sdk-2-individual-modules): Complete module catalog