Deployed gateway baseline and scope
This guide matches the deployed oneaster-gateway commit f09a2d5da1c9b6fbfd95ae4246080a8489d44564. On 2026-11-17, read-only checks of server current, service working directories and source digests confirmed deployment revision f09a2d5. GET https://api.oneaster.ai/api/status reported build version 7ba12de+oneaster.0.1.0 (quota_per_unit: 1000000, production Base URL https://api.oneaster.ai, inference Base URL https://api.oneaster.ai/v1). Model availability, group ratios, and prices are configured by administrators per deployment. The API reference, public OpenAPI, and Try it runner target this deployed version. Download OpenAPI.
Four API surfaces and authentication boundaries
First, the /v1 inference surface accepts only personal inference API Keys (Authorization: Bearer sk-..., or x-api-key on POST /v1/messages) and serves OpenAI and Anthropic native JSON, SSE, binary audio/video, and async task protocols. /v1 never accepts a login access_token or Personal Access Token (PAT, nap_...), and does not use /pg persistent request intents; do not treat Idempotency-Key as a required header on /v1/chat/completions or assume universal idempotent replay across /v1 protocols.
Second, the /pg logged-in wallet Playground surface accepts only a native login access_token (Authorization: Bearer $ONEASTER_ACCESS_TOKEN), bills the caller's wallet directly, and enforces owner isolation (user_id matching; foreign or missing records return 404) plus a trusted browser Origin (with CORS credentials disabled). /pg rejects inference API Keys (sk-...) and PATs (nap_...), and never secretly creates or exposes API Keys.
Third, the /oneaster/v1 TypeScript business and governance facade returns {data:...} on success and {error:{code,message}} on failure. It authenticates with a native login access_token (or a scoped PAT where supported; /oneaster/v1/task-diagnostics* requires a live login session and rejects PATs and inference Keys; admin routes additionally require live administrator role permissions).
Fourth, native /api handles login, registration, MFA, account security, and low-level administration, usually returning {success,message,data} where business errors can still return HTTP 200. PR #49 introduces native Google OAuth authentication via initiation endpoint POST /api/oauth/state and completion endpoint POST /api/oauth/google. For every flow, the frontend BFF generates a fresh 32-byte random unpadded base64url browser_binding (43 characters; replace the example placeholder and never reuse a constant), calls POST /api/oauth/state with intent: "login", stores the state and binding in an encrypted HttpOnly cookie (recommended __Host-oneaster-google-flow, SameSite=Lax), and redirects the user to authorization_url. On Google redirect to frontend GET /oauth/google, the BFF verifies the flow cookie and state, then calls backend POST /api/oauth/google. Backend GET /api/oauth/google returns 405; do not put authorization codes in backend URLs or persistent logs. The frontend GET callback temporarily receives code/state and must redirect to a clean same-site URL after validation. Accounts with active MFA receive require_verification: true and must complete verification via POST /api/user/login/verify. Live GET /api/status does not currently list Google under custom_oauth_providers; backend deployment does not imply public enablement or completed Google Console testing.
Session Playground (/pg) persistent intents and recovery (PR #39)
Every /pg write endpoint (POST /pg/chat/completions, /pg/responses, /pg/messages, /pg/images/generations, /pg/images/edits, /pg/videos, /pg/audio/speech, /pg/audio/transcriptions, /pg/audio/translations, /pg/tasks/kie) accepts Idempotency-Key (1–100 printable ASCII characters without spaces; generate a client UUID v4 and persist it in sessionStorage before sending). The idempotency namespace is account-wide per user_id across all /pg write routes: reusing the same Idempotency-Key with a different method, path, query, or payload returns 409 idempotency_conflict without running inference or billing. Omitting Idempotency-Key remains backward-compatible (the gateway generates X-OneAster-Intent-ID), but if the connection drops before response headers arrive, by-intent recovery is unavailable.
/pg responses include X-OneAster-Intent-ID, X-OneAster-Request-ID, Location: /pg/requests/{request_id}, and Cache-Control: private, no-store, plus X-OneAster-Reused: true on deduplicated replay and Retry-After: 3 on 409 request_in_progress.
After a page refresh, disconnect, or timeout, recover via GET /pg/requests/by-intent?intent_id={UUID} or GET /pg/requests/{request_id}; never automatically re-send POST. Bodies up to 4 MiB (4194304 bytes) are retained for 24 hours, with the deadline in result_expires_at. response.body is a string: parse JSON or SSE according to response.content_type and check response.complete. JSON/SSE have no encoding field; only binary /pg/audio/speech uses response.encoding="base64". When a body is too large, unavailable, or expired, GET still returns HTTP 200 with result_available=false and response=null while preserving deduplication and billing state. Never treat missing output as permission to generate again. Repeating POST has different replay errors: 409 result_expired for expired output, 409 stream_replay_unavailable for completed SSE, or 409 result_unavailable for other non-replayable output.
In-progress requests heartbeat every 10 seconds; if a running record has no heartbeat for more than 45 seconds, the GET recovery view returns status=unknown and retry_allowed=false, without an execution_state_unknown error field. billing_state is independently derived from billing evidence and is unknown, reserved, settled, or released. charge_quota and reserved_quota are null when unconfirmed and never zero-filled. Uninitialized storage returns 503 intent_storage_unavailable.
curl --request GET "https://api.oneaster.ai/pg/requests/by-intent?intent_id=00000000-0000-4000-8000-000000000001" \ --header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN"
Public documentation Try it boundary
The Try it panel on API reference pages executes only whitelisted /v1 inference API Key operations. It never accepts a login access_token, never calls /pg or /oneaster/v1, never performs account, payment, or admin writes, and never automatically retries billable requests. Suno POST /v1/tasks/kie is not on the Try it whitelist.