create session token

Create a new session token used to initialise Anam client side SDKs

POST /v1/auth/session-token

create session token

cURL

curl --request POST \
  --url https://api.anam.ai/v1/auth/session-token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "personaConfig": {
    "name": "Cara",
    "avatarId": "071b0286-4cce-4808-bee2-e642f1062de3",
    "voiceId": "de23e340-1416-4dd8-977d-065a7ca11697",
    "llmId": "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
    "systemPrompt": "You are a helpful assistant."
  }
}
'

200

{
  "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.signature"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Configuration for the session to be created. Supply personaConfig.personaId to use a persona you've already created (stateful), or the set avatarId/voiceId/llmId/systemPrompt to configure the persona at run time (ephemeral).

The returned token is valid for one hour, or for expiresInSeconds when set, and bound to this exact config.

Server-side SDKs in a secure context can skip this exchange and start a session directly by calling POST /v1/engine/session with their API key and the same configuration in the request body.

clientLabel · string

The client label for the session

maxSessions · integer

The most sessions the token can start. Omit it for no limit (the default). Each call to POST /v1/engine/session with the token counts, including one that fails, so set maxSessions: 1 only when your client starts the session once and gets a new token to retry. The Anam JS SDK retries a failed start up to 3 times by default: send maxSessions: 3, or set the SDK's retry.maxAttempts to 1. Reconnects and ICE restarts within a session don't count. Once the limit is reached, session start returns 401. If the API key has its own limit, the lower of the two applies.

Required range: 1 <= x <= 100

Example:

1

expiresInSeconds · integer · default: 3600

How long the token can start sessions, in seconds, from 120 (2 minutes) to 3600 (1 hour). Omit it for one hour. The token is checked only when a session starts: once it expires, POST /v1/engine/session returns 401, but a session it already started keeps running until it ends. Start the session within this time, including any retries your client makes.

Required range: 120 <= x <= 3600

Example:

300

personaConfig · Ephemeral persona · object

Persona configuration. An avatar-only config (avatarId without voiceId and without enableAudioPassthrough: true) is only accepted together with a LiveKit, Agora or ElevenLabs Agent integration environment; on the default Anam WebRTC transport send an ephemeral config with voiceId and llmId (llmId "CUSTOMER_CLIENT_V1" for a client-side LLM) or set enableAudioPassthrough to true. Otherwise the request fails with 400 avatar_only_requires_integration.

Ephemeral persona

Avatar with audio passthrough

Saved persona

Show child attributes

environment · object

Optional engine routing or transport integration environment. The integration type may be supplied explicitly or inferred from the LiveKit, Agora, or ElevenLabs Agent settings.

Option 1

Option 2

Option 3

Option 4

Show child attributes

sessionOptions · object

Show child attributes

Response

200

application/json

Successfully started session

Short-lived credential used by a client to connect to a live persona. Valid for one hour, or for the expiresInSeconds it was created with, and only while that API key stays active.

sessionToken · string

Signed JWT the client passes to the Anam SDK to open a WebRTC connection.