Skip to content

Starbase API Binary Responsibilities

The API binary handles all synchronous, request-response interactions:

  • Dashboard API — Project CRUD, service CRUD, deployment history, billing dashboard, user settings, team management — the full contract lives at Dashboard API
  • Shuttle endpoints — Serves desired state, receives snapshots, receives capacity reports (see Shuttle API Contract §25)
  • Git webhooks — Receives push events from GitHub/GitLab/Bitbucket, validates signatures, enqueues build jobs
  • Stripe webhooks — Receives payment events (invoice paid, payment failed, subscription cancelled), updates billing state — signature-verified, deduped via stripe_events; the consumed set and effects live at Billing › Stripe lifecycle
  • Auth / sessions — OAuth flow for SSO providers, session management, JWT issuance for dashboard (Auth & Sessions)
  • Telemetry query broker — Serves the dashboard's logs/metrics reads: routes each query to the region(s) hosting the environment's services and injects the server-side tenant filter as bound parameters (FR-065, Observability v2 · Read & query). Written against a small QueryTransport interface — the per-region transport switch: a direct ClickHouse connection over VPC peering for DO regions (MVP, and permanently), the Mass Relay outbound stream (§39.3 #43) for regions on clouds without DO peering — so adding or switching a region's transport is a wiring change, not a rewrite
  • Operator admin surface — operator-authenticated endpoints for region and cluster registration: validates a region manifest (adapter factory exists, transport valid, live connectivity probes), owns region status transitions, and mints cluster identity (bearer + ingest tokens) — Region Onboarding

Does NOT do

Long-running operations. If a request would take more than a few seconds (build, cluster provisioning, DB provisioning), the API enqueues a job and returns immediately — the Worker binary §14 picks it up.

RBAC is enforced here, but defined elsewhere

Permission middleware in the API binary enforces the two-tier permission model on every dashboard request. The model itself — roles, the environment protection flag, the three database tables — lives in the Starbase RBAC page: RBAC model → §15.

Cross-references

The async counterpart → §14 · the Shuttle endpoints' payloads → §25.1 · Git webhook security, dedup, and debounce → Starforge §16.11 · the desired-state contract the Shuttle endpoint serves → §32.