switchboard HTTP API
Inbound webhook ingestion and the local-only web UI for switchboard.
Three groups of endpoints
- Webhook ingestion (
/webhooks/*): providers POST here. Signed providers are verified-or-rejected (401, not persisted); the generic endpoint uses a shared-secret token (or open). - Operator API (
/api/v1/*): OAuth-guarded (operator grants) — register agents, vend endpoints, list what you own. TheswitchboardCLI is its reference client. - Web UI (
/,/log,/providers,/settings) + the SSE stream (/events): server-rendered HTML (html/template + HTMX) plus atext/event-streamfor live updates.
Authentication posture (ADR-0001, brief §8)
The service is localhost-bound by default and ships no in-app auth for the UI. If it is
ever exposed on the homelab LAN it MUST sit behind Caddy forward_auth — auth is provided by
the reverse proxy, not built into this app for the MVP. The UI/SSE/health endpoints below are
therefore marked security: [] (no in-app auth) by design, not by oversight.
For webhook endpoints, "authentication" means per-provider signature verification
(signed providers) or a shared-secret token that authenticates the caller (generic). See ADR-0003.
Authentication
- API Key: githubSignature
- API Key: stripeSignature
- API Key: slackSignature
- API Key: genericToken
- HTTP: Bearer Auth
HMAC-SHA256 of the raw body, sha256= prefixed.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-Hub-Signature-256 |
t= timestamp + v1= HMAC-SHA256 over "{t}.{body}".
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | Stripe-Signature |
v0= HMAC-SHA256 over "v0:{ts}:{body}"; paired with X-Slack-Request-Timestamp.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-Slack-Signature |
Shared-secret token — authenticates the caller, not the body (ADR-0003).
Security Scheme Type: | apiKey |
|---|---|
Query parameter name: | token |
An OPERATOR OAuth grant (ADR-0019/ADR-0023): an opaque access token minted by the
authorization-code + PKCE flow with resource = <base>/api, bound to the signed-in human.
Endpoint-bound tokens and static sbk_ credentials do NOT resolve here. The switchboard
CLI performs this flow (gh-style) and stores the rotating pair locally.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | opaque |
Contact Joe Stump:
License MIT