Authentication

There are exactly two ways for a client to start a conversation with your agent. Pick one — there is no third path, and your API key is never one of them in the browser.

Public agent ID

The browser calls Fish Audio directly with just an agentId. No credential — requires the agent to be public.

Session token

Your backend creates a session with your API key and hands the short-lived token to the SDK. The default for private agents.

	Public agent ID	Session token
Credential in browser	None	Short-lived session token
Requires	Agent set to public + allowed origins	Your own backend endpoint
Session parameters set by	The SDK (`overrides`, `dynamicVariables`, `language`, `toolEvents` options)	Your backend, in the creation request
Best for	Demos, marketing pages, low-friction embeds	Production apps with signed-in users

Public agents: connect with an agent ID

If the agent is public, the SDK creates the session itself — no backend, no credential:

JavaScript

import { AgentSession } from "@fishaudio/agent-client";

const session = await AgentSession.start({
  agentId: "YOUR_AGENT_ID",
  dynamicVariables: { name: "Ada" },
});

Fish Audio accepts the request only when the agent has public access enabled and the page’s Origin is on the agent’s allow-list; requests are rate-limited per IP and per agent. Origins match on exact scheme, host, and port — localhost and 127.0.0.1 are different origins, so list both during development. See Public agents for setup.

Session tokens: mint on your backend

For private agents, your backend exchanges your API key for a single-conversation token.

Create a session from your backend

Call POST /v1/agent/sessions with your API key. This is where you set per-session parameters — user identity, overrides, dynamic variables.

Return the response to your frontend

The response is the session token. Forward it verbatim.

Start the SDK with the token

Pass the object to AgentSession.start({sessionToken}) unmodified. The SDK handles the connection from there.

curl --request POST https://api.fish.audio/v1/agent/sessions \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "YOUR_AGENT_ID",
    "end_user_id": "user_42",
    "dynamic_variables": { "name": "Ada" }
  }'

app.post("/voice-session", async (req, res) => {
  const upstream = await fetch("https://api.fish.audio/v1/agent/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FISH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: "YOUR_AGENT_ID",
      end_user_id: req.user.id,
      dynamic_variables: { name: req.user.name },
    }),
  });
  if (!upstream.ok) {
    console.error("session creation failed:", upstream.status);
    return res.status(502).json({ error: "session_unavailable" });
  }
  res.json(await upstream.json());
});

import os
import requests

def create_voice_session(end_user_id: str, name: str) -> dict:
    response = requests.post(
        "https://api.fish.audio/v1/agent/sessions",
        headers={"Authorization": f"Bearer {os.environ['FISH_API_KEY']}"},
        json={
            "agent_id": "YOUR_AGENT_ID",
            "end_user_id": end_user_id,
            "dynamic_variables": {"name": name},
        },
    )
    response.raise_for_status()
    return response.json()

import { AgentSession } from "@fishaudio/agent-client";

const sessionToken = await fetch("/voice-session", { method: "POST" }).then(r =>
  r.json()
);

const session = await AgentSession.start({ sessionToken });

In session token mode, overrides, dynamic_variables, language, tool_events, timezone, and world_context belong in your backend’s creation request — the SDK forwards these options only in public agent ID mode.

Request fields

Field	Type	Description
`agent_id`	string, required	The agent to talk to. It must have a published version.
`name`	string, optional	Display name for this session in the console’s Conversations list, up to 128 characters. Omit it to show the session’s start time instead. API-key requests only — keyless (public) creation rejects it with `400`.
`language`	string, optional	Shorthand for `overrides.language`; subject to the same override allow-list. See Voice & language.
`overrides`	object, optional	Per-session config overrides. Each field must be enabled in the agent’s override allow-list — unauthorized fields are rejected with `400`.
`dynamic_variables`	object, optional	Up to 50 entries of string, number, or boolean values, substituted into `{{placeholders}}`. See Dynamic variables.
`tool_events`	boolean, optional	Stream tool lifecycle events (`toolCallStarted` / `toolCallCompleted` / `toolCallFailed`) to the client. Default `true`; set `false` to keep tool inputs and outputs off the client.
`end_user_id`	string, optional	Your identifier for the end user, for attribution in conversation history.
`metadata`	object, optional	Your own key-value namespace. Stored and returned verbatim on session queries and webhooks — never read or interpreted by the platform.
`record_audio`	boolean, optional	Whether to record this session’s audio. Overrides the agent’s recording setting for this session only — it never changes the agent; omit it to use the agent’s configuration.
`timezone`	string, optional	IANA timezone (like `Asia/Shanghai`) for the agent’s sense of local time. Invalid names are rejected with `422`. See Time & timezone.
`client_timezone`	string, optional	The end user’s browser timezone, filled automatically by the SDK in public-agent mode. A hint, not a demand: it applies only when neither `timezone` nor the agent’s configured timezone is set, and invalid values are ignored. See the resolution order.
`world_context`	boolean, optional	Whether the agent knows the current date and time. Default `true`; set `false` to withhold both from this session.

Unknown fields — top-level or inside overrides — are rejected with 422.

Response

JSON

{
  "session_id": "abc123",
  "expires_at": "2026-07-23T12:00:00Z",
  "max_duration_seconds": 1800,
  "transport": "livekit",
  "livekit_url": "wss://example.livekit.cloud",
  "token": "<participant token>"
}

Field	Description
`session_id`	The session’s id — use it later to look up the conversation record.
`expires_at`	Deadline for the client to connect. Mint the token right before starting, not ahead of time.
`max_duration_seconds`	Hard cap on session length.
`transport`	Which transport the SDK uses for this session; `livekit` today.
`livekit_url`, `token`	Connection details for that transport, consumed by the SDK.

Treat the response as opaque and pass it to start() unmodified. If the SDK does not recognize the transport value, it fails fast with an unsupported_transport error asking you to upgrade the SDK — it never silently degrades.

Token lifetime

A session token is single-use: start() consumes it once to establish the conversation.
On network drops the SDK reconnects at the transport level using the same connection state — it never re-creates the session, so you never need to re-mint mid-call.
Once a session ends, the token is spent. Mint a new token for each conversation.

Ending sessions from your backend

A session normally ends from the client side — the user disconnects, or the agent hangs up. To force-end a live session server-side, call the end endpoint with your API key and the session_id from the creation response:

Request

curl --request POST https://api.fish.audio/v1/agent/sessions/$SESSION_ID/end \
  --header "Authorization: Bearer $FISH_API_KEY"

The agent disconnects and the call terminates — the response is 204. The session record stays readable in conversation history, along with the transcript and recording when the agent stores them. The same endpoint ends in-progress phone calls too.

Keep API keys on the server

Your API key grants full access to every resource in your team — agents, sessions, tools, phone numbers. Never embed it in a browser, mobile app, or any code you ship to users. The only credential that belongs in a client is the session token, and the only credential-free path is a public agent ID.

Error responses

Session creation fails with standard HTTP statuses; the SDK surfaces them as a FishAgentError with statusCode set.

Status	Meaning
`400`	An `overrides` field is not on the agent’s override allow-list.
`401`	Invalid API key. A request with no `Authorization` header at all is treated as a public-agent request instead.
`402`	Quota exceeded.
`403`	Public-agent request rejected: the agent is not public, or the page’s `Origin` is not on the allow-list.
`409`	Conflict — most commonly the agent has no published version yet. Publish to resolve.
`422`	The request body failed validation — an unknown field, an unsupported `language` code, an invalid `timezone`, or an invalid dynamic variable.
`429`	Rate limited — a public-agent request exceeded the per-agent or per-IP limit.

The complete status-code reference for every /v1/agent endpoint — error shapes, 400 vs 422, conflict semantics — is on Agents API errors.

Going further

Public agents

Enable credential-free access with origin allow-lists.

Web SDK

Everything AgentSession can do once connected.

React SDK

Hooks and components for React apps.

Dynamic variables

Personalize each session at creation time.

Get Started

Build

Test

Deploy

Telephony

Monitor

Public agent ID

Session token

Public agents: connect with an agent ID

Session tokens: mint on your backend

Request fields

Response

Token lifetime

Ending sessions from your backend

Keep API keys on the server

Error responses

Going further

Public agents

Web SDK

React SDK

Dynamic variables

Public agent ID

Session token

​Public agents: connect with an agent ID

​Session tokens: mint on your backend

​Request fields

​Response

​Token lifetime

​Ending sessions from your backend

​Keep API keys on the server

​Error responses

​Going further

Public agents

Web SDK

React SDK

Dynamic variables

Public agents: connect with an agent ID

Session tokens: mint on your backend

Request fields

Response

Token lifetime

Ending sessions from your backend

Keep API keys on the server

Error responses

Going further