Temporary Sessions

Give each of your client applications or devices its own short-lived session token instead of your account API Key.

Overview

Your API Key is long-lived and grants access to your whole account. Never ship it inside a mobile app, a browser or a device.

A temporary session solves this. Your backend creates it with one request, hands it to the client, and the client connects to one Palabra real-time product with it. The token is limited by rules you choose:

Field	What it limits
intent	Product: speech-to-speech translation (s2s), speech-to-text (stt) or text-to-speech (tts)
connection_type	Transport: WebSocket (ws) or WebRTC (webrtc)
expires_in_seconds	Connect window: how long the token can be used to open a stream
max_session_duration_seconds	The longest a single stream can run
single_use	Whether the token works for one stream only
client_reference_id	Your own identifier of the user or device, for filtering and reporting

Palabra refuses a token that breaks one of these rules and returns a specific error code, so your client can tell the user what happened. Streams opened with a session token are billed to your account like any other stream.

tip

Create temporary sessions on a backend server you control, never in the client. The client only ever sees the token value.

Creating a temporary session

Endpoint: POST /session-storage/v2/sessions

Headers:

• Authorization: Bearer <API_KEY>
• Content-Type: application/json

Request Body:

Field	Type	Required	Description
intent	string	yes	s2s, stt or tts
connection_type	string	no	ws (default) or webrtc. webrtc is available for s2s only
expires_in_seconds	integer	no	Connect window, 60–86400. Default 3600
max_session_duration_seconds	integer	no	Longest duration of one stream, 60–18000. No limit if omitted
single_use	boolean	no	true — the token works for one stream only. Default false
client_reference_id	string	no	Your identifier of the user or device, up to 256 characters
subscriber_count	integer	no	Number of listener tokens to issue, 0–100. WebRTC only

Example Request:

POST /session-storage/v2/sessions HTTP/1.1
Host: api.palabra.ai
Content-Type: application/json
Authorization: Bearer <your-api-key>

{
  "intent": "stt",
  "connection_type": "ws",
  "single_use": true,
  "expires_in_seconds": 300,
  "max_session_duration_seconds": 3600,
  "client_reference_id": "device-17"
}

import requests

def create_token(api_key: str, device_id: str) -> str:
    resp = requests.post(
        "https://api.palabra.ai/session-storage/v2/sessions",
        json={
            "intent": "stt",
            "connection_type": "ws",
            "single_use": True,
            "expires_in_seconds": 300,
            "max_session_duration_seconds": 3600,
            "client_reference_id": device_id,
        },
        headers={"Authorization": f"Bearer {api_key}"},
    )
    resp.raise_for_status()
    return resp.json()["data"]["token"]

Response: HTTP 201 Created

{
  "ok": true,
  "data": {
    "id": "ses_k3v9x2m7q4t8w1z5b6n0c2d4",
    "token": "<session-token>",
    "intent": "stt",
    "connection_type": "ws",
    "single_use": true,
    "client_reference_id": "device-17",
    "status": "pending",
    "created_at": "2026-10-05T10:00:00Z",
    "connect_by": "2026-10-05T10:05:00Z",
    "max_session_duration_seconds": 3600,
    "first_connected_at": null,
    "active_stream_count": 0
  }
}

• id — session ID. Use it to inspect or revoke the session.
• token — the token your client connects with. Treat it as an opaque string. It is returned here and in Get Session by ID only.
• connect_by — moment after which the token can no longer open a new stream.
• status — see Session lifecycle.
• webrtc — present for connection_type: webrtc only: url, room_name and the listener tokens in subscriber_keys (returned on creation only).

Each call creates an independent session, even with the same client_reference_id. If a request fails on your side and you retry it, the unused session expires at its connect_by.

Usage type

intent and connection_type bind the token to one product and one transport. A speech-to-text token presented to the translation endpoint is refused with intent_mismatch; a WebSocket token presented over WebRTC is refused with connection_type_mismatch.

Expiration

expires_in_seconds sets the connect window. Until connect_by the token can open a stream; afterwards it is refused with connect_window_expired. A stream that is already running is not interrupted when the window closes.

Single use

With single_use: true the token opens exactly one stream. A second connection is refused with session_already_used, also when the first stream is still running. With single_use: false the token can run several streams at the same time, up to the concurrent session limit of your plan.

Max session duration

max_session_duration_seconds applies to each stream separately. When a stream reaches the limit the client receives max_duration_reached and the connection closes. Without this field a stream runs as long as the client keeps it open.

Connecting with a session token

Use token wherever the product documentation asks for the token, exactly as for any other session. The endpoints per product and transport are listed in Session Management.

Session lifecycle

The statuses are the same as for any session (see Session lifecycle). Two of them are specific to the limits on this page:

• used — a single-use session whose stream has finished; it cannot open another one.
• expired — the connect window set by expires_in_seconds has passed and no stream is running.

Running streams of all your sessions count toward the concurrent session limit of your plan; a connection over the limit is refused with session_limit_reached. There is also a cap on sessions that were created but not used yet; over the cap, creating a session returns pending_sessions_limit_reached. Revoke sessions you no longer need instead of waiting for them to expire.

If your account runs out of balance or is blocked, running streams are closed and new connections are refused.

Tracking and revocation

client_reference_id is your label for the user or device behind the token. Use it as the client_reference_id filter of List Sessions to find the sessions of one user, and Delete Session to revoke a token: it stops working for new connections at once, and a running stream receives session_revoked and closes within the heartbeat interval.

Streams opened with a session token are billed to your account like any other stream.

Errors

Two refusals exist only because of the limits on this page:

error_code / reason	HTTP	What happened and what to do
202100 session_already_used	409	A single-use token is presented a second time. Request a new session.
202102 max_duration_reached	410	The stream reached max_session_duration_seconds. Request a new session for a new stream.

All other refusals, the two ways a client receives them and the full code table are in Session Management → Errors.