API Reference

The Amba API is a single Hono service on GCP Cloud Run. Everything is HTTPS + JSON. No gRPC, no GraphQL, no SOAP.

Base URL

https://api.amba.dev

The same host serves every plane — routing is by path prefix:

Auth model

Developer Bearer (admin + /auth/developer/me)

Obtained via POST /auth/developer/login (or /signup). The access token is a short-lived JWT; the refresh token is long-lived and rotated on every POST /auth/developer/refresh.

Authorization: Bearer <developer-access-token>

Admin routes under /admin/projects/:projectId/* additionally enforce project ownership — the developer must own the referenced project or the request is rejected with 403 PROJECT_FORBIDDEN.

Client API key + session token (/client/*)

Every client request must include the project's client API key (amb_client_ck_…). After the SDK signs a user in, it attaches the returned session token as a Bearer alongside the API key:

X-Api-Key: amb_client_ck_xxx
Authorization: Bearer <session-token>

/client/auth/* and /client/config accept requests with only X-Api-Key — they run before a session exists. Everything else requires both headers.

Webhooks

/webhooks/revenuecat uses RevenueCat's X-RevenueCat-Signature HMAC header. /webhooks/superwall uses Superwall's X-Superwall-Signature HMAC. Both are rate-limited and verified before any state mutation.

Response envelope

Every handler returns one of two shapes:

// success
{ "data": <payload> }
 
// failure
{ "error": { "code": "STRING_CODE", "message": "Human-readable message", "details": { /* optional */ } } }

Status codes follow REST conventions:

• 200 OK — read succeeded
• 201 Created — resource created
• 400 — validation / input error
• 401 — missing or invalid auth
• 403 — auth present but not permitted (e.g. project ownership failed)
• 404 — resource not found
• 409 — conflict (duplicate, state machine refused the transition)
• 429 — rate-limited
• 500 — unexpected server error
• 502 — upstream failed (push provider, Neon control plane, Temporal)

Pagination

List endpoints that support pagination accept ?limit= and ?cursor= query params and return:

{
  "data": [
    /* items */
  ],
  "pagination": { "next_cursor": "opaque-string-or-null", "total": 123 }
}

Cursor is opaque — don't parse it. Absence of next_cursor means the last page.

Idempotency

Creation endpoints that enqueue Temporal workflows (push campaigns, project provisioning, reprovisioning) are idempotent on their workflow id. Duplicate starts surface as 409 ALREADY_SCHEDULED or 409 ALREADY_RUNNING.

Rate limiting

Developer auth endpoints (/auth/developer/signup, /login, /refresh) and webhooks are rate-limited per-IP with two-tier buckets (fast-window + daily-window). See individual endpoint pages for the exact thresholds.

Sections

• Admin API — developer-side project and resource management (28 modules).
• Client API — SDK-facing surface for end users (27 modules).
• Developer Auth — signup, login, refresh, logout, me.
• Webhooks — RevenueCat + Superwall.