Authentication

Every connection is tied to your account with an API key. There are two ways to use it, depending on whether the code runs on your server or in an untrusted client (a browser or mobile app).

Server-side: your secret key

From your own backend, send your secret key in the Authorization header when you open the connection:

Authorization: Bearer swaram_your_key_here

Your secret key looks like swaram_…, is shown once when you create it, and is stored only as a hash — keep it on your server. Never put a swaram_ key in a browser or app, where a user could read it.

Browser / mobile: a short-lived token

Untrusted clients shouldn't hold your secret key. Instead, your backend mints a short-lived ephemeral token (it looks like swaram_ek_…) and hands only that to the client. The token can carry locked settings — model, voice, instructions, tools — that the client can't change, and it expires after a minute or so.

1. On your backend, exchange your secret key for a token:

import httpx

resp = httpx.post(
    "https://api.swaram.live/v1/realtime/client_secrets",
    headers={"Authorization": "Bearer swaram_your_key_here"},
    json={
        "model": "mal-realtime-simple",
        "session": {
            "instructions": "You are a friendly Malayalam assistant.",
            "voice": "mal-female",
        },
    },
)
token = resp.json()["value"]   # a swaram_ek_… token — send THIS to the client

2. In the client, connect with that token. Browsers can't set headers on a WebSocket, so pass it as a subprotocol:

const ws = new WebSocket(
  "wss://api.swaram.live/v1/realtime?model=mal-realtime-simple",
  ["realtime", "openai-insecure-api-key." + token]
);

A bad or expired token is rejected and the connection closes (code 4001).

How the key is read

The server looks for your credential in this order:

1. Authorization: Bearer <key> header — the server-side path.
2. ?api_key=<key> query parameter.
3. Sec-WebSocket-Protocol: openai-insecure-api-key.<key> subprotocol — the browser path.

Config at creation

Whichever path you use, send your configuration at the start — in the token, or as the first session.update right after you connect. It's locked once the conversation begins. See Sessions & context for the details.

← All docs