Skip to main content

​
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>
Content-Type: application/json

​
Response

On success, the server returns a JSON object with two fields: 
{
  "token": "<session_token>",
  "ws_url": "wss://host/api/v1/sdk/ws"
}
FieldDescription
tokenShort-lived JWT valid for 5 minutes. Used to authenticate the WebSocket connection.
ws_urlThe WebSocket endpoint URL to connect to.

​
Error Responses

StatusDescription
401 UnauthorizedInvalid or missing API key. Check your Authorization header.
403 ForbiddenAPI key is valid but the kiosk is inactive or disabled.
500 Internal ErrorServer-side issue. Retry after a short delay.

​
Best Practices

  • Request a fresh token for each voice session — do not cache or reuse tokens
  • Use the token immediately after receiving it — it expires in 5 minutes
  • If the WebSocket connection fails, request a new token before reconnecting
  • Handle authentication errors gracefully and provide user feedback

​
Health Check

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" }

​
Next Steps

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