DOCS/Technical Docs/API Reference

API Reference

This reference describes the Cloudflare auth-worker implemented in this repository, not the earlier illustrative rack/workload API. There is no repo-backed /v1/racks, /v1/workloads, API-token settings screen, CLI, or published SDK implementation here.

Base URL

The dashboard uses VITE_AUTH_URL, defaulting to https://auth.yoba.systems. Set it to http://localhost:8787 for a local worker. Routes below include their full /api prefix. In production, marketing contact and newsletter requests default directly to VITE_AUTH_URL (fallback https://auth.yoba.systems) at /api/contact and /api/newsletter; no production web-worker API forwarding is required. VITE_API_URL overrides the contact base (the form appends /contact, so include /api), and VITE_NEWSLETTER_ENDPOINT overrides the full newsletter endpoint. Development keeps the existing https://api.yoba.systems/contact contact default and same-origin /api/newsletter with a Vite proxy unless overridden.

Authentication and Authorization

Protected routes require a signed Better Auth session cookie. Roles and permissions differ by endpoint: platform admin/operator, platform super-admin, organization member, and organization owner/admin are distinct checks. See Authentication and Endpoints.

Errors and Rate Limits

Handlers generally return JSON errors; validation, authentication, authorization, missing resources, conflicts, rate limiting, and upstream service failures can produce 400, 401, 403, 404, 409, 429, 502, or 503 responses. Better Auth has its own response contract. Newsletter confirmation returns HTML; unsubscribe returns a state object. There is no Free/Pro/Enterprise request-quota contract implemented here. Worker rate limits depend on the route and configured Cloudflare bindings (src/middleware/rate-limit.ts).

Integration Scope

Use the dashboard's Better Auth client for login, password resets, two-factor challenges, and organization invitations. Use the implemented HTTP routes for organization, catalog, billing, newsletter, contact, and account-data workflows. No official Go, Python, or TypeScript SDK release is verified by this repository.