Authentication

Token Endpoint

To start a voice session, send a POST request with your API key to receive a session token and WebSocket URL.

POST /api/v1/sdk/token
Authorization: Bearer <your_api_key>

On success, the server returns a JSON object with two fields:

{
  "token": "<session_token>",
  "ws_url": "wss://host/api/v1/sdk/ws"
}

Field	Description
`token`	Short-lived JWT valid for 5 minutes. Used to authenticate the WebSocket connection.
`ws_url`	The WebSocket endpoint URL to connect to.

Status	Description
401 Unauthorized	Invalid or missing API key. Check your Authorization header.
403 Forbidden	API key is valid but the kiosk is inactive or disabled.
500 Internal Error	Server-side issue. Retry after a short delay.

Use the heartbeat endpoint to verify your API key and check server availability before starting a session.

POST /api/v1/sdk/heartbeat
Authorization: Bearer <your_api_key>

// Response 200
{ "status": "ok" }

Once you have a token, continue to the WebSocket Protocol page to learn how to establish the connection and start streaming audio.