Browser voice agents with session tokens

Use a 10-minute session token to let a browser talk to a voice agent without exposing your API key.

Short answer. A session token from POST /v1/agents/{id}/sessions gives a browser 10-minute access to one agent only, without needing your API key. Send the token as a Bearer token in the Authorization header on the next request.

Why use session tokens

Your API key grants access to all agents and endpoints. A session token is scoped to a single agent and expires after 10 minutes, so it is safe to send to a browser. This lets you build voice interfaces that run in the browser without exposing your full credentials.

Get a session token

Call POST /v1/agents/{id}/sessions with your agent-scoped key or full API key. The response includes a token valid for 10 minutes.

Request a session token

curl -X POST https://speakvora.com/api/v1/agents/{id}/sessions \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json"

# Response
{"token": "st.eyJhZ2VudCI6Im15LWFnZW50LWlkIn0..."}

Use the token in the browser

Pass the token as a Bearer token in the Authorization header. The browser can now send turns to the agent without your API key.

Send a turn with a session token

const token = "st.eyJhZ2VudCI6Im15LWFnZW50LWlkIn0...";

const response = await fetch(
  "https://speakvora.com/api/v1/agents/{id}/turn",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      session: "browser-session-1",
      text: "What are your hours?"
    })
  }
);

const result = await response.json();
console.log(result.reply);

Token scope and expiry

A session token reaches only the agent it was issued for. It expires after 10 minutes. If the token expires, request a new one from your backend.

Token is valid for 10 minutes
Token reaches only one agent
Token cannot be used to call other endpoints or agents
Request a new token when the old one expires

Typical flow

Your backend requests a session token, sends it to the browser, and the browser uses it to talk to the agent. When the token expires, the browser asks your backend for a new one.

Backend calls POST /v1/agents/{id}/sessions with your API key
Backend sends the token to the browser
Browser sends turns with Authorization: Bearer <token>
After 10 minutes, browser requests a new token from the backend

Agents are beta

Voice agents are in beta. Session tokens work with the agent turn endpoint. Phone calls and texting are not yet available through session tokens.

Frequently asked questions

Can I use a session token to call other endpoints?

No. A session token reaches only the agent it was issued for. To call other endpoints, use your full API key on your backend.

What happens when the token expires?

Request a new token from your backend and retry the turn.

Is the token safe to send to a browser?

Yes. The token is scoped to one agent and expires after 10 minutes, so the risk is limited. Your full API key should stay on your backend.

Can I use a session token with WebSocket streaming?

Yes. Send the token as a Bearer token in the Authorization header when you connect to the WebSocket.