---
title: "Session Management"
url: "https://developer.incode.com/sdk-reference/web-sdk-2-session-api/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Advanced"
version: "v1.1"
status: "live"
---
# Session Management

:::note
This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](/sdk-reference/web-sdk-reference).  Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade. <br /><br />Full rollout to all clients still TBD.
:::

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

```typescript
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)

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

```ts
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');
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()`:

```typescript
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:

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

const result = await getFinishStatus();
// result.action: 'approved' | 'rejected' | 'none'
// result.scoreStatus: 'OK' | 'WARN' | 'MANUAL_OK' | 'FAIL' | 'UNKNOWN' | 'MANUAL_FAIL'
// result.redirectionUrl: string
```

## See Also

- [Getting Started](/sdk-reference/web-sdk-2-getting-started/): Basic integration
- [API Reference](/sdk-reference/web-sdk-2-reference/): Full API documentation
- [IncodeFlow Component](/sdk-reference/web-sdk-2-incodeflow-component/): Rendering the flow