Session Management

Warning

This guide is specific to Web SDK 2.x. For Web SDK 1.x, you can find documentation here.

Do not attempt to upgrade or implement without support. Contact your Incode representative to check if you are a candidate for this upgrade.

Sessions authenticate users with the Incode API. Sessions must be created before rendering any SDK component.

Creating a Session

Use createSession() from @incodetech/core/session:

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

// Create session (typically on your backend, or client-side for dev)
const session = await createSession('your-api-key', {
  configurationId: 'your-config-id',
  language: 'en-US',
  externalId: 'optional-user-id', // Links session to your own user record
});

// Setup SDK with the token
await setup({
  apiURL: 'https://demo-api.incodesmile.com',
  token: session.token,
});

Security note: Embedding your API key in client-side code is acceptable for development, but for production you should create the session on your backend and pass only the token to the frontend.

Server-Side Session Creation (Recommended for Production)

Create the session token on your backend, then pass it to the frontend:

Backend (Node.js example)

const response = await fetch('https://demo-api.incodesmile.com/omni/start', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-api-key': process.env.INCODE_API_KEY,
    'api-version': '1.0',
  },
  body: JSON.stringify({
    configurationId: 'your-config-id',
    language: 'en-US',
  }),
});

if (!response.ok) {
  throw new Error(`Failed to create Incode session: ${response.status}`);
}

const { token } = await response.json();
// Send token to frontend

Frontend

import { setup } from '@incodetech/core';
import '@incodetech/web/flow';
import '@incodetech/web/flow/styles.css';

// Token received from your backend
await setup({
  apiURL: 'https://demo-api.incodesmile.com',
  token: sessionToken,
});

const flow = document.querySelector('incode-flow');
if (flow) {
  flow.config = { token: sessionToken, lang: 'en-US' };
  flow.onFinish = (result) => {
    /* ... */
  };
}

Session Lifecycle

Sessions expire after a configured timeout (set in your dashboard)
Each verification step updates the session state on the backend
Create a new session for each new verification attempt

External ID

Associate sessions with your own user identifiers by passing externalId to createSession():

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

const session = await createSession('your-api-key', {
  configurationId: 'your-config-id',
  externalId: 'your-user-id-123',
});

This allows you to link Incode sessions to users in your system.

Getting the Finish Status

After a flow completes, retrieve the final verification result:

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

const result = await getFinishStatus('YOUR_CONFIGURATION_ID');
// Or: await getFinishStatus(undefined) to omit the flow filter.
// Optional cancellation: getFinishStatus('YOUR_CONFIGURATION_ID', signal).
// result.action: 'approved' | 'rejected' | 'none'
// result.scoreStatus: 'OK' | 'WARN' | 'MANUAL_OK' | 'FAIL' | 'UNKNOWN' | 'MANUAL_FAIL'
// result.redirectionUrl: string

The first argument is required and accepts string | undefined | null; the second is an optional AbortSignal.

result.endScreenTitle and result.endScreenText are always null from this helper. The orchestrated Flow's onFinish result fills these nullable fields from Dashboard copy received at session creation. Use that callback result when rendering the configured completion text.