> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lagena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Session lifecycle

> Create, refresh, observe, and end sessions safely.

## Create

Every create request requires an idempotency key between 1 and 200 characters:

```ts theme={null}
const session = await client.createSession({
  idempotencyKey: crypto.randomUUID(),
  digitalHumanId,
});
```

Reuse the same key only when retrying the same logical request. A new intended
session needs a new key. The SDK does not retry automatically.

## Connect

An active or connectable session contains `session.connection`:

```ts theme={null}
if (!session.connection) {
  throw new Error("Session is not connectable");
}
```

Return that value to the authorized browser. Avoid storing the participant
token as durable application state.

## Refresh access

Read the session from your server when the browser needs fresh connection
credentials:

```ts theme={null}
const refreshed = await client.getSession(sessionId);
return refreshed.connection;
```

The connection is `null` after a session reaches a terminal state.

## Observe state

Sessions use these states:

| State | Meaning |
| - | - |
| `created` | Session creation has started |
| `active` | The session can be joined |
| `completed` | The session finished normally |
| `failed` | The session could not continue |
| `cancelled` | The session was explicitly ended |

## End

```ts theme={null}
const ended = await client.endSession(sessionId);
```

Ending an already terminal session is safe. Ending a session does not erase
its historical record.

<Note>
  A browser disconnect does not necessarily end the API session. End it from
  your server when your product knows the experience is finished.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.