Sessions and authentication

Before opening a WebSocket, you obtain an access token and create a session.

Obtain an access token

Exchange your connector token for a short-lived JWT access token. POST /api/v1/access-token

Headers

Header	Required	Description
`X-Token`	Yes	Your connector token (provided by PolyAI)
`X-Host`	Yes	The domain or app namespace you registered when generating the token (e.g. `https://www.yourcompany.com` or `com.yourcompany.app`). Must match exactly.
`Content-Type`	Yes	`application/json`

Request body

{}

Response — `200 OK`

{
  "access_token": "eyJhbGc...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Field	Type	Description
`access_token`	string	JWT to use for all subsequent requests
`expires_in`	integer	Seconds until the token expires
`token_type`	string	Always `"Bearer"`

Use this token in two places:

As a Bearer token in the Authorization header for Create session
As the access_token query parameter when connecting the WebSocket

Treat the access token as sensitive. Do not log it, store it in localStorage, or expose it to third-party scripts. Always connect over wss:// (TLS).

Create session

A session represents one conversation. Create a session before opening a WebSocket. POST /api/v1/sessions

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <access_token>` from the previous step
`Content-Type`	Yes	`application/json`
`User-Agent`	No	The browser or device user agent

Request body (optional)

{
  "platform": "web",
  "streaming_enabled": true
}

Field	Type	Default	Description
`streaming_enabled`	boolean	`false`	When `true`, agent responses arrive as a series of incremental chunks. When `false`, each response arrives as a single complete message. See Streaming.
`platform`	string	`web`	One of `web`, `ios`, `android`, `ios-web`, `android-web`, or `custom`. Use `ios` / `android` from native SDKs that post to this endpoint directly. The webchat script reports `web`, `ios-web`, or `android-web` automatically based on its `data-platform` attribute — you don’t need to set this field when embedding the script.

The request body is optional — if omitted, streaming_enabled defaults to false.

Response — `200 OK`

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Keep the session_id — you need it to open the WebSocket and to reconnect if the connection drops.

Sessions expire after roughly 10 minutes of inactivity. After expiry, create a new session — you cannot resume an expired session.

API reference

Build & deploy

Runtime & data

Monitoring

Legacy

Sessions and authentication

Obtain an access token

Headers

Request body

Response — `200 OK`

Create session

Headers

Request body (optional)

Response — `200 OK`

​Obtain an access token

​Headers

​Request body

​Response — 200 OK

​Create session

​Headers

​Request body (optional)

​Response — 200 OK

Obtain an access token

Headers

Request body

Response — `200 OK`

Create session

Headers

Request body (optional)

Response — `200 OK`