WebSocket authentication

Overview

Send your API key when you open the connection, in the Authorization header or in the protocols list. The connection is yours from the moment it opens, so you can open it early and start streaming the instant you have audio or text.

This works on the Speech-to-Text and Text-to-Speech WebSocket APIs. Use a regular key from the Soniox Console on your servers and a temporary API key in client apps.

Still sending api_key in the start message? That works until 15 January 2027; see Migrate WebSocket authentication.

Send the API key with the connection

Authorization header

The standard HTTP header, sent on the WebSocket upgrade request. Most server-side WebSocket libraries can set it, for example websockets in Python and ws in Node.js.

Authorization: Bearer <SONIOX_API_KEY>

import asyncio, json, os
import websockets

async def main():
    async with websockets.connect(
        "wss://stt-rt.soniox.com/transcribe-websocket",
        additional_headers={"Authorization": f"Bearer {os.environ['SONIOX_API_KEY']}"},
    ) as ws:
        # No api_key in the start message.
        await ws.send(json.dumps({"model": "stt-rt-v5", "audio_format": "auto"}))
        # ... send audio, read responses ...

asyncio.run(main())

import WebSocket from "ws";

const ws = new WebSocket("wss://stt-rt.soniox.com/transcribe-websocket", {
  headers: { Authorization: `Bearer ${process.env.SONIOX_API_KEY}` },
});

ws.on("open", () => {
  // No api_key in the start message.
  ws.send(JSON.stringify({ model: "stt-rt-v5", audio_format: "auto" }));
});

Protocols list

Browsers cannot set headers on a WebSocket. Instead, pass the key as the second argument of new WebSocket(url, protocols): the entry soniox-api-key followed by the key. The browser sends this list in the Sec-WebSocket-Protocol header.

const ws = new WebSocket("wss://stt-rt.soniox.com/transcribe-websocket", [
  "soniox-api-key",
  temporaryApiKey, // from your backend, see the temporary API keys guide
]);

ws.onopen = () => {
  // No api_key in the start message.
  ws.send(JSON.stringify({ model: "stt-rt-v5", audio_format: "auto" }));
};

A bad key does not fail the handshake: onopen fires, then an error frame with error_code and error_type arrives in onmessage, and the server closes the connection.

Text-to-Speech

The Authorization header and the protocols list work the same way on Text-to-Speech. Leave api_key out of the config message.

const ws = new WebSocket("wss://tts-rt.soniox.com/tts-websocket", [
  "soniox-api-key",
  temporaryApiKey,
]);

ws.onopen = () => {
  // No api_key in the config message.
  ws.send(JSON.stringify({
    stream_id: "stream-1",
    model: "tts-rt-v2",
    language: "en",
    voice: "Adrian",
    audio_format: "pcm_s16le",
    sample_rate: 24000,
  }));
  ws.send(JSON.stringify({ stream_id: "stream-1", text: "Hello!", text_end: true }));
};

Rules

• One key per connection. The key sent with the connection is the connection's key for its whole life. Every stream on that connection runs on it.
• Leave api_key out of the start message. The same key is accepted, a different one is refused. See Migrate WebSocket authentication.
• Use the Authorization header or the protocols list, not both. Sending both, soniox-api-key without a key, or a malformed Authorization value gets a 400 error frame and the connection closes.
• Authentication errors arrive as an error frame after the connection opens, not as a failed handshake, so browsers can read them.
• Temporary keys. Temporary keys start with snx_temp_ and work in the Authorization header and in the protocols list. A key in the older temp: format is not a valid protocols list entry; send it in the Authorization header.
• Single-use temporary keys. A single-use key sent with the connection allows exactly one stream on that connection. On Text-to-Speech, where one connection can carry several streams, use a regular temporary key at connect if you need more than one stream.

Connection timeouts

Sending the key with the connection lets you open the connection before you have anything to send, and start the instant you do. The connection has no deadline for its first stream: it stays open as long as you keep it alive, and it counts against your connection limit the whole time.

Speech-to-Text

Send a keepalive, {"type": "keepalive"}, at least every 40 seconds until the start request, or the connection is closed as idle with WebSocket status 1001. Once the stream has started, the keepalive rules apply as before.

Text-to-Speech

Send any message, for example {"keep_alive": true}, at least every 40 seconds, or the connection is closed as idle with WebSocket status 1001. After the first stream the same rule applies between streams: a message at least every 40 seconds, see keepalive.

Connection limit

Every open WebSocket connection counts against a connection limit, separate from your concurrency limit. It stops idle connections piling up.

• The limit is a multiple of your concurrent requests limit (Speech-to-Text) or concurrent streams limit (Text-to-Speech). It applies per organization, and per project where a project limit is set. Raising your concurrency limit in the Soniox Console raises the connection limit with it.
• A connection is counted about one second after it opens, or from its start message if that comes first. It is released when it closes.
• A connection slot is not a stream slot. You can hold more connections than streams, but starting a stream still needs a free stream slot.
• Over the limit, the next connection gets a 429 max_concurrent_connections_reached error frame and is closed. Close connections you are not using, or start streams on the ones you hold.

Speech-to-Text connections carry one stream and close with it, so the connection limit only matters there for connections opened ahead of time. Text-to-Speech connections stay open between streams, so count the connections you keep, not the streams you run.

Errors

All other errors, for example a missing permission or an exhausted balance, arrive as an error frame in response to the start message.