API Reference
SkyState's HTTP API is primarily consumed by the CLI, console, and SDKs. This reference documents the current route surface for maintainers and advanced integrations.
All product routes are versioned under /v1. Health and webhooks are unversioned.
Auth Schemes
| Scheme | Header | Used by |
|---|---|---|
| SkyState Bearer | Authorization: Bearer <jwt> | Developer sessions and end-user sessions |
| API key | Authorization: ApiKey <sky_...> | Project-scoped automation and public-state writes |
| Anonymous | no Authorization header | public-state reads, public auth config, auth exchange routes, health, and webhooks |
Firebase ID tokens are accepted only by POST /v1/auth/authorize/callback as hosted-login proof. Product routes do not accept Firebase tokens directly.
Route Groups
| Route group | Auth | Purpose |
|---|---|---|
/v1/auth/* | Anonymous | Developer and end-user Authorization Code + PKCE-shaped exchange |
/v1/auth/dev/* | Anonymous | Developer CLI copy/paste code helper |
/v1/{accountId}/projects | Developer bearer | Project CRUD, API keys, and end-user auth settings |
/v1/{accountId}/projects/{slug}/public-state | Developer bearer or API key | Public-state read/write/patch/version history |
/v1/readonly/{accountId}/projects/{slug}/public-state | Anonymous | SDK/browser public-state reads |
/v1/{accountId}/projects/{slug}/user-states | Developer bearer | Developer list/show/delete for end-user state |
/v1/{accountId}/projects/{slug}/user-state | End-user bearer | Signed-in end-user state read/write |
/v1/readonly/{accountId}/projects/{slug}/auth/end-user/config | Anonymous | Public end-user auth config |
/v1/api-key/info | API key | Metadata for the authenticated API key |
/v1/account | Developer bearer | Account profile, update, delete, and agreement acceptance |
/v1/billing | Developer bearer | Checkout, portal, tier changes, subscription resume, and usage status |