API reference

API reference: introduction

Cloud Control API basics: the base URL, session-cookie vs. Bearer-token authentication, the JSON error shape, enumeration safety, and login/rate-lockout behavior.

The Cloud Control API is JSON over HTTPS. This reference documents the real, shipping endpoints; request and response shapes match the running handlers. Every documented route is org-scoped where it returns data, and cross-organization identifiers return 404.

Base URL

On the live deployment the base URL is https://cloud-control.snoweasl.com. Locally it is http://localhost:3000. All paths below are relative to the base URL.

Authentication

There are two ways to authenticate:

Session cookie — set by `POST /api/auth/login` (and MFA verify). Used by the browser; httpOnly, SameSite=Lax, Secure in production.
Bearer API token — Authorization: Bearer cc_pat_… from API tokens. Used by scripts and CI. The token's role is a capability ceiling and never carries owner or platform powers.

Some routes accept either (for example GET /api/auth/me, GET /api/cloud/resources, GET /api/audit, GET /api/org/users). Sensitive administration — SSO config, token management, ownership transfer, platform admin — requires a session and rejects Bearer tokens.

The error shape

Errors are a JSON object with a human-readable error string and the appropriate HTTP status. Some errors carry extra fields (for example a missing array on a cloud permission error, or existingId on a duplicate).

json

{ "error": "Not signed in." }

Status codes

Status	Meaning
`200` / `201` / `202`	Success (`201` created, `202` accepted for async work like sync).
`400`	Malformed body or failed validation.
`401`	Not signed in, or an unknown/expired/revoked token or session.
`403`	Signed in but lacking the required capability (on member-visible surfaces).
`404`	Not found — also returned for cross-org ids and for hidden surfaces (platform admin) to unauthorized callers.
`409`	Conflict — for example a duplicate email or an already-connected cloud account.
`429`	Rate-locked — too many failed sign-in or MFA attempts; carries `Retry-After`.
`503`	The service can't reach its database or a required keyring right now.

Enumeration safety & lockout

Authentication endpoints never reveal whether an email exists; wrong-email and wrong-password sign-ins return the identical response, and password-reset returns the same body either way. Five failed sign-ins per email (existing or not) lock that email for 15 minutes with a 429; the same cap applies to wrong MFA codes. See Login protection.