​
Authorize Client Session

To connect a client (browser or mobile app) to a Layercode voice pipeline, 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/pipelines/authorize_session) using your LAYERCODE_API_KEY. Your backend then returns the client_session_key to the frontend.

Once your frontend receives the client_session_key, it can connect to the Layercode WebSocket API to start streaming audio.

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/pipelines/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

​
pipeline_id
string
required

The ID of the Layercode pipeline the client should connect to.

​
session_id
string

(Optional) The session ID to resume an existing session. If not provided, a new session will be created.

​
Response

​
client_session_key
string
required

The key your frontend uses to connect to the Layercode WebSocket API.

​
session_id
string
required

The unique session ID for this conversation.

​
Example Request

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

# Example with pipeline_id and session_id (resumes an existing session)
curl -X POST https://api.layercode.com/v1/pipelines/authorize_session \
  -H "Authorization: Bearer $LAYERCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pipeline_id": "pl-123456", "session_id": "lc_session_abc123..."}'

​
Example Response

{
  "client_session_key": "lc_sesskey_abc123...",
  "session_id": "lc_session_abc123..."
}

​
Error Responses

​
error
string
required

Error message describing the problem.

Possible error cases:

  • 400 – Invalid or missing bearer token, invalid pipeline ID, missing or invalid session 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/pipelines/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.pipeline_id) {
    throw new Error("Missing pipeline_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.

Once your frontend receives the client_session_key, it can connect to the Layercode WebSocket API to start streaming audio.