Developer docs

Add AI chat, customer auth, and usage billing without running a backend

Switchboard gives frontend and mobile apps a project-hosted backend URL, SDK-managed end-user sessions, OpenAI-compatible chat, and Stripe checkout without exposing provider secrets.

Start quickstart OpenAPI

How Switchboard works

Switchboard sits between your client app, model providers, and Stripe. Your frontend only knows a generated project backend URL and the customer's end-user session. The provider key, usage ledger, model pricing, billing target, and subscription state stay on Switchboard.

1. Project

Create a hosted backend

Each project gets a backend URL like <project_backend_url>. Add your web origins or mobile app identifiers before shipping.

2. Customer

Register or sign in

The hosted auth API returns an sb_eusr_ token. Store it in local storage for web prototypes or secure storage for mobile.

3. Chat

Call OpenAI-compatible chat

Your app posts messages to the hosted backend. Switchboard authenticates the end user, checks billing state, calls the provider, and streams the response back.

4. Billing

Meter usage and collect payment

Token usage is priced from the model catalog, recorded in the ledger, and reported either to customer billing or developer billing in Stripe.

No-backend quickstart

Create a project, copy its hosted backend URL, and let the SDK store the customer's `sb_eusr_` session. Your app sends chat requests through Switchboard instead of putting provider API keys in browser or mobile code.

  1. 1 Install @switchboard/sdk.
  2. 2 Set SWITCHBOARD_PROJECT_BACKEND_URL from the dashboard integration kit.
  3. 3 Register or sign in the end user, then call chat completions.
app.js 
  import { createSwitchboardHostedClient } from "@switchboard/sdk";

const client = createSwitchboardHostedClient({
  backendUrl: import.meta.env.SWITCHBOARD_PROJECT_BACKEND_URL,
  storage: {
    getToken: () => localStorage.getItem("sb_eusr"),
    setToken: (token) => localStorage.setItem("sb_eusr", token),
    clearToken: () => localStorage.removeItem("sb_eusr"),
  },
});

const session =
  (await client.auth.getSession()) ??
  (await client.auth.register("user@example.com", "secure-password-here"));

const canChat =
  session.endUser.billing_status === "sandbox" ||
  session.endUser.billing_status === "active";

if (!canChat) {
  throw new Error("Customer needs checkout before using chat");
}

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "Hello" }],
});

Integration examples

Use the hosted SDK path for browser and mobile apps. Use secret keys only from a trusted server, CI job, or smoke test where the key cannot be extracted by customers.

streaming.js 
  const stream = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  stream: true,
  stream_options: { include_usage: true },
  messages: [{ role: "user", content: "Write a three-line welcome." }],
});

for await (const chunk of stream) {
  const token = chunk.choices?.[0]?.delta?.content;
  if (token) appendToken(token);
}
server.js 
  import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SWITCHBOARD_SECRET_KEY,
  baseURL: "https://switchboard.spot/v1",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "Hello from a trusted server" }],
});

React or Vite

Put the project backend URL in an environment variable, create one SDK client, and hydrate the end-user session during app boot.

Native mobile

Store sb_eusr_ in Keychain or encrypted storage. Use app links or custom schemes for checkout success and cancel URLs.

Existing backend

Keep using the OpenAI SDK with Switchboard as the base URL. Put sb_test_ or sb_live_ only in server-side configuration.

Credential boundaries

Use the weakest credential that can do the job. Secret project keys and account sessions stay out of client apps.

sb_sess_

Account session

CLI and account management API. Never use it in browser or mobile code.

sb_test_ / sb_live_

Secret project key

Trusted servers, CI, and smoke tests. Full gateway access for a project.

sb_pub_test_ / sb_pub_live_

Publishable key

Client-safe compatibility flow. Secondary to hosted backend URLs for new apps.

sb_eusr_

End-user session

Customer session for hosted chat, checkout, profile, billing portal, and logout.

Billing, pricing, and checkout

Sandbox end users can chat immediately. For live usage, choose Developer-funded, Metered, or Credit wallet billing. Switchboard prices each request from the model catalog, records token usage, and reports the correct charge to Stripe.

Metered: customer charge is provider token cost plus Switchboard's 15% provider-cost margin plus your project markup.

Developer-funded: your organization pays provider token cost plus Switchboard's 15% provider-cost margin; end-user charge is zero.

Credit wallet: customers pay recurring wallet credits through Connect; usage debits wallet balance and is recovered through developer billing.

Catalog rates: available from GET /v1/catalog/models with per-million-token prices and a pricing source.

Status Typical app behavior
sandbox Allow sandbox chat while testing.
active Allow paid chat.
pending Show checkout or wait for completion.
past_due Open the billing portal.
blocked Disable chat and show support copy.
checkout.js 
  // End-user paid mode: customer checkout on the connected account.
const { checkout_url } = await client.auth.checkout({
  success_url: "https://yourapp.com/billing/success",
  cancel_url: "https://yourapp.com/billing/cancel",
});

window.location.assign(checkout_url);

1. Pick billing mode

Use Metered when customers pay per use, Developer-funded when usage is bundled, or Credit wallet when customers buy recurring credits that carry forward.

2. Complete Stripe setup

Metered projects need Connect onboarding. Developer-funded projects need active developer billing. Credit wallet projects need both.

3. Let Stripe invoice usage

Each completion is metered by request ID. Switchboard routes usage to the connected account meter or the platform developer billing meter.

API reference

Hosted backend routes use your project backend URL. Public catalog routes live under the standard API base. The OpenAPI document covers the gateway, auth, checkout, and account API surfaces.

Endpoint Use
POST <project_backend_url>/end_user_auth/register Create an end-user session.
POST <project_backend_url>/chat/completions OpenAI-compatible chat with `sb_eusr_`.
POST <project_backend_url>/end_user_auth/checkout Create hosted checkout.
GET /v1/models List OpenAI-compatible model IDs.
GET /v1/catalog/models List catalog pricing.

Ready to ship API-key-free LLMs?

Create a project and call OpenAI-compatible chat without shipping provider secrets.

Start building