​
Authorize Client Session

To connect a client (browser or mobile app) to a Layercode voice agent, you must first authorize the session. This is done by calling the Layercode REST API endpoint below from your backend. How the authorization flow works: When using a Layercode frontend SDK (such as @layercode/react-sdk or @layercode/js-sdk), the SDK will automatically make a POST request to the authorizeSessionEndpoint URL that you specify in your frontend code. This authorizeSessionEndpoint should be an endpoint on your own backend (not Layercode’s). Your backend receives this request from the frontend, then securely calls the Layercode REST API (https://api.layercode.com/v1/agents/web/authorize_session) using your LAYERCODE_API_KEY. Your backend then returns the client_session_key to the frontend.
Scheduled change: Monday 1 September at 12:00 UTC — the response body will return conversation_id instead of session_id. Until then, you will continue to receive session_id. Plan your upgrade accordingly.
Your Layercode API key should never be exposed to the frontend. Always call this endpoint from your backend, then return the client_session_key to your frontend.

​
Endpoint

POST https://api.layercode.com/v1/agents/web/authorize_session

​
Headers

​
Authorization
string
required
Bearer token using your LAYERCODE_API_KEY.
​
Content-Type
string
default:"application/json"
required
Must be application/json.

​
Request Body

​
agent_id
string
required
The ID of the Layercode agent the client should connect to.
​
conversation_id
string
(Optional) The conversation ID to resume an existing conversation. If not provided, a new conversation will be created.

​
Response

​
client_session_key
string
required
The key your frontend uses to connect to the Layercode WebSocket API.
​
conversation_id
string
required
The unique conversation ID.
​
config
object
Optional configuration for this session used by the frontend SDK. When present, it can include:
transcription.trigger, transcription.automatic, transcription.can_interrupt, and VAD settings such as vad.enabled, vad.gate_audio, vad.buffer_frames, vad.model, vad.positive_speech_threshold, vad.negative_speech_threshold, vad.redemption_frames, vad.min_speech_frames, vad.pre_speech_pad_frames, vad.frame_samples.

​
Example Request

# Example with only agent_id (creates a new session)
curl -X POST https://api.layercode.com/v1/agents/web/authorize_session \
  -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "ag-123456"}'

# Example with agent_id and conversation_id (resumes an existing conversation)
curl -X POST https://api.layercode.com/v1/agents/web/authorize_session \
  -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "ag-123456", "conversation_id": "lc_conv_abc123..."}'

​
Example Response

{
  "client_session_key": "lc_sesskey_abc123...",
  "conversation_id": "lc_conv_abc123..."
}

​
Error Responses

​
error
string
required
Error message describing the problem.
Possible error cases:
  • 400 – Invalid or missing bearer token, invalid agent ID, missing or invalid conversation ID.
  • 402 – Insufficient balance for the organization.
Example error response: 
{
  "error": "insufficient balance"
}

​
Example: Backend Endpoint (Next.js)

Here’s how you might implement an authorization endpoint in your backend (Next.js example):
Next.js app/api/authorize/route.ts
export const dynamic = "force-dynamic";
import { NextResponse } from "next/server";

export const POST = async (request: Request) => {
  // Here you could do any user authorization checks you need for your app
  const endpoint = "https://api.layercode.com/v1/agents/web/authorize_session";
  const apiKey = process.env.LAYERCODE_API_KEY;
  if (!apiKey) {
    throw new Error("LAYERCODE_API_KEY is not set.");
  }
  const requestBody = await request.json();
  if (!requestBody || !requestBody.agent_id) {
    throw new Error("Missing agent_id in request body.");
  }
  try {
    const response = await fetch(endpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${apiKey}`,
      },
      body: JSON.stringify(requestBody),
    });
    if (!response.ok) {
      const text = await response.text();
      throw new Error(text || response.statusText);
    }
    return NextResponse.json(await response.json());
  } catch (error: any) {
    console.log("Layercode authorize session response error:", error.message);
    return NextResponse.json({ error: error.message }, { status: 500 });
  }
};
For other backend frameworks (Express, FastAPI, etc.), the logic is the same: receive a request from your frontend, call the Layercode authorize_session endpoint with your API key, and return the client_session_key to your frontend.

​
Sessions

​
Get Session Details

GET https://api.layercode.com/v1/agents/{agent_id}/sessions/{session_id}
​
Authorization
string
required
Bearer token using your LAYERCODE_API_KEY.

​
Response

Returns JSON with details about the session, transcript, and recording status.
​
session_id
string
required
Connection ID for the session.
​
agent_id
string
required
ID of the agent.
​
started_at
string
ISO timestamp when the connection started.
​
ended_at
string
ISO timestamp when the connection ended (if ended).
​
duration_ms
number
Total connection duration in milliseconds.
​
metadata
object
Custom metadata associated with the session.
​
from_phone_number
string
Caller phone number (Twilio), if applicable.
​
from_phone_country
string
Caller country code (Twilio), if applicable.
​
to_phone_number
string
Agent phone number (Twilio), if applicable.
​
to_phone_country
string
Agent phone number country code (Twilio), if applicable.
​
ip_address
string
IP address of the connection.
​
country_code
string
Country code derived from IP address when available.
​
transcription_duration_seconds
number
Total seconds of user speech.
​
tts_duration_seconds
number
Total seconds of generated speech.
​
latency_ms
number
Processing latency in milliseconds.
​
transcript
array
Array of transcript entries. Each entry includes: timestamp, user_message, assistant_message, latency_ms.
​
recording_status
string
One of not_available, in_progress, completed.
​
recording_url
string
If recording_status is completed, a URL to download the WAV recording for this session connection.

​
Example

curl -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  https://api.layercode.com/v1/agents/ag-123456/sessions/lc_conn_abc123

​
Download Session Recording

GET https://api.layercode.com/v1/agents/{agent_id}/sessions/{session_id}/recording
​
Authorization
string
required
Bearer token using your LAYERCODE_API_KEY.
Returns a WAV audio file if available. 
curl -L -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -o session.wav \
  https://api.layercode.com/v1/agents/ag-123456/sessions/lc_conn_abc123/recording
Recordings are generated after a session completes. If a recording is still processing, the details endpoint will return recording_status: “in_progress”.
Once your frontend receives the client_session_key, it can connect to the Layercode WebSocket API to start streaming audio.