# Session Management

<WebSDK2 />

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](doc:web-sdk-2-getting-started): Basic integration
* [API Reference](doc:web-sdk-2-reference): Full API documentation
* [IncodeFlow Component](doc:web-sdk-2-incodeflow-component): Rendering the flow