Session lifecycle

Create

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

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.

An active or connectable session contains session.connection:

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.

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

const refreshed = await client.getSession(sessionId);
return refreshed.connection;

The connection is null after a session reaches a terminal 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

const ended = await client.endSession(sessionId);

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

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