# Switchboard

> Switchboard is API-key-free LLM integration for builders shipping user-facing
> AI with hosted auth, metering, checkout, billing gates, and OpenAI-compatible
> chat without exposing provider secrets.

Use this file as the compact agent discovery map for Switchboard. For fuller
product context, read `/switchboard-knowledge.md`. For API contracts, read
`/v1/openapi.json`.

## Credential layers

| Layer | Prefix | Where | Used for |
|-------|--------|-------|----------|
| Account session | `sb_sess_` | CLI, server automation | `/v1/account/*` management API |
| Secret project key | `sb_test_` / `sb_live_` | Server, CI, CLI only | Full gateway, `POST /v1/end_users` (server checkout) |
| Publishable key | `sb_pub_test_` / `sb_pub_live_` | Browser, mobile app | `GET /v1/models`, `GET /v1/catalog/models`, chat, `/v1/end_user_auth/*` |
| End-user session | `sb_eusr_` | Secure client storage | Live chat + checkout with publishable key |

Never embed secret keys (`sb_test_`, `sb_live_`, `sb_sess_`) in client code.

## Quick start (sandbox, server)

1. Sign up at the dashboard (email/password or GitHub/GitLab OAuth).
2. Copy your `sb_test_` sandbox API key from the dashboard (shown once), or run:
   `switchboard keys regenerate-sandbox --json`
3. Point the OpenAI SDK at Switchboard:

   - `SWITCHBOARD_API_KEY` — secret sandbox key (`sb_test_...`)
   - `SWITCHBOARD_BASE_URL` — `http://localhost:4000/v1` (dev) or `https://switchboard.spot/v1` (prod)

4. Optional header for live billing: `X-Switchboard-End-User: <your-user-id>`

## Quick start (browser / mobile, no custom backend)

1. Copy the project **publishable sandbox** key (`sb_pub_test_...`) from the dashboard or:
   `switchboard keys regenerate-publishable-sandbox --json`
2. Register allowed origins on the project:
   `switchboard projects update <id> --allowed-origins http://localhost:5173`
3. Use `@switchboard/sdk` or call `/v1/end_user_auth/register` and `/v1/end_user_auth/session`.

See https://switchboard.spot/docs/no-backend.md

## CLI (agents and automation)

Install: `curl -fsSL https://switchboard.spot/install.sh | bash` (local: `http://localhost:4000/install.sh` after `mix cli.pack`)

- Pass `--json` on any command for machine-readable stdout.
- `switchboard auth register` / `switchboard auth login`
- `switchboard keys regenerate-sandbox --json`
- `switchboard keys regenerate-publishable-sandbox --json`
- `switchboard projects update <id> --allowed-origins <url,...>`
- `switchboard chat test --json`
- `switchboard end-user-auth register --email ... --password ...` (publishable key)
- `switchboard integration kit --json` — env, snippets, `agent_prompt`, checklist
- `switchboard init --agent` — write `.env.local` and agent manifest JSON

See https://switchboard.spot/docs/cli.md

## First-party docs

- [Switchboard homepage](https://switchboard.spot/)
- [Developer docs](https://switchboard.spot/docs): Public quickstart, credentials, billing, and API routes.
- [No-backend browser/mobile guide](https://switchboard.spot/docs/no-backend.md): Hosted end-user auth and client-safe chat.
- [Server integration guide](https://switchboard.spot/docs/integration.md): Trusted server setup with OpenAI-compatible requests.
- [Billing and Stripe Connect docs](https://switchboard.spot/docs/billing.md): Billing modes, customer charges, and checkout.
- [CLI reference](https://switchboard.spot/docs/cli.md): Account, project, key, and integration kit commands.
- [Agent knowledge file](https://switchboard.spot/switchboard-knowledge.md): Full product context for AI assistants.
- [OpenAPI schema](https://switchboard.spot/v1/openapi.json)

## Repository docs

- [GitHub repository](https://github.com/switchboard-dev/switchboard)
- [CLI reference](https://github.com/switchboard-dev/switchboard/blob/main/docs/cli.md)
- [Server integration guide](https://github.com/switchboard-dev/switchboard/blob/main/docs/integration.md)
- [No-backend browser/mobile guide](https://github.com/switchboard-dev/switchboard/blob/main/docs/no-backend.md)
- [Billing and Stripe Connect docs](https://github.com/switchboard-dev/switchboard/blob/main/docs/billing.md)

## Discovery

- OpenAPI: `/v1/openapi.json`
- Models (OpenAI-compatible): `GET /v1/models`
- Catalog + pricing: `GET /v1/catalog/models` (LiteLLM bootstrap once; daily empirical sync from OpenAI costs)
- Integration Kit (Bearer secret key or account session): `GET /v1/integration_kit` and `GET /v1/account/integration_kit`
- Agent handoff: dashboard **Use with AI** or `agent_prompt` field in the integration kit JSON

## Gateway routes (summary)

| Endpoint | Secret key | Publishable key |
|----------|------------|-----------------|
| `POST /v1/chat/completions` | Yes | Yes (live needs end-user session unless embed_mode) |
| `POST /v1/end_users` | Yes | No |
| `POST /v1/end_user_auth/register` | No | Yes |
| `POST /v1/end_user_auth/session` | No | Yes |
| `POST /v1/end_user_auth/checkout` | No | Yes (+ session header) |

## Pricing model

End-user paid mode: customer charge = provider cost + Switchboard 15% provider-cost margin + developer markup.
Developer-paid mode: developer charge = provider cost + Switchboard 15% provider-cost margin; end-user charge is zero.

## Docs

- [Server integration](https://switchboard.spot/docs/integration.md)
- [No-backend browser/mobile guide](https://switchboard.spot/docs/no-backend.md)
- [Billing and Stripe Connect](https://switchboard.spot/docs/billing.md)
- [CLI reference](https://switchboard.spot/docs/cli.md)

## Optional

- [GitHub server integration source](https://github.com/switchboard-dev/switchboard/blob/main/docs/integration.md)
- [GitHub no-backend source](https://github.com/switchboard-dev/switchboard/blob/main/docs/no-backend.md)
- [GitHub billing source](https://github.com/switchboard-dev/switchboard/blob/main/docs/billing.md)
- [GitHub CLI source](https://github.com/switchboard-dev/switchboard/blob/main/docs/cli.md)