DOCS/Technical Docs/API Reference/Endpoints

Endpoints

These paths are registered by apps/auth-worker/src/index.ts. Protected requests use Better Auth session cookies; see Authentication. There are no implemented /v1/racks, /v1/workloads, workload-log streams, or rack metrics endpoints here.

Public and Better Auth Routes

MethodPathAccess / behavior
GET/api/healthHealth JSON when environment validation succeeds
GET, POST/api/auth/*Better Auth login/session/signup/reset/two-factor/organization plugin routes; access varies by action
GET/api/invitations/:invitationIdPublic id, role, status, expiry; no recipient email or org name
POST/api/contactPublic validated contact intake
POST/api/newsletterPublic double opt-in signup
GET/api/newsletter/confirm?token=…HTML confirmation result
GET/api/newsletter/unsubscribe?token=…JSON state: unsubscribed, already_unsubscribed, expired, or invalid

Organizations, Members, and Assets

All /api/orgs routes require a session, including catalog routes mounted under that prefix. Org-admin/member helpers permit platform super-admin bypasses; billing checks do not.

MethodPathRequired access
GET, POST/api/orgsPlatform super-admin plus system-org membership
GET, POST/api/orgs/:orgId/membersOrg owner/admin or platform super-admin
PUT/api/orgs/:orgId/members/:userId/roleOrg owner/admin or platform super-admin; cannot change own role
DELETE/api/orgs/:orgId/members/:userIdOrg owner/admin or platform super-admin; cannot remove self; account preserved
GET/api/orgs/:orgId/invitationsOrg owner/admin or platform super-admin
DELETE/api/orgs/:orgId/invitations/:invitationIdOrg owner/admin or platform super-admin
GET/api/orgs/:orgId/assetsOrg member or platform super-admin
GET/api/orgs/:orgId/assets/:assetIdOrg member or platform super-admin
POST/api/orgs/:orgId/assetsOrg owner/admin or platform super-admin
PUT, DELETE/api/orgs/:orgId/assets/:assetIdOrg owner/admin or platform super-admin

Invitation creation/acceptance uses the Better Auth organization plugin, not a custom POST invitations route. Custom member creation takes name/email/password and optional role, creates an account through Better Auth, then inserts membership; it is not cross-service atomic. Assets are stored records, not provisioning or machine-control operations.

Catalog and Billing

MethodPathRequired access / behavior
GET/api/orgs/billing/categoriesAuthenticated session; active categories
GET/api/orgs/billing/categories/:id/productsAuthenticated session; products/prices
GET/api/orgs/billing/products/:idAuthenticated session; product details
GET/api/orgs/billing/packagesAuthenticated session; package components
POST/api/orgs/billing/sync-catalogPlatform super-admin plus system-org membership
GET/api/orgs/:orgId/available-plansOrg member or platform super-admin; recurring plans
GET/api/orgs/:orgId/subscriptionOrg member or platform super-admin; legacy latest-subscription view
GET/api/orgs/:orgId/subscriptionsOrg member or platform super-admin; subscriptions with items
GET/api/orgs/:orgId/invoicesOrg member or platform super-admin; paginated Stripe invoices
GET/api/orgs/:orgId/payment-methodTarget org owner/admin membership
POST/api/orgs/:orgId/checkoutTarget org owner/admin membership; Stripe Checkout URL
POST/api/orgs/:orgId/portalTarget org owner/admin membership; Stripe Portal URL
POST/api/orgs/:orgId/add-addonTarget org owner/admin membership
DELETE/api/orgs/:orgId/add-on/:itemIdTarget org owner/admin membership

Checkout requires a catalog-backed Stripe priceId; quantity defaults to 1. Optional addons contain priceId/quantity and must match the base category. An existing active/trialing subscription in the category causes a 409 conflict. One-time unit prices use payment mode; other purchases use subscription mode. Subscription state is synced through Stripe webhooks.

typescript

The identifiers above are placeholders, not recorded API results.

Platform Administration and Account Data

MethodPathRequired access
GET/api/admin/usersPlatform admin/operator
POST/api/admin/usersPlatform admin
PUT/api/admin/users/:id/rolePlatform admin
DELETE/api/admin/users/:idPlatform admin
GET/api/admin/audit-logsPlatform admin/operator; filters/pagination
GET/api/gdpr/exportAuthenticated user; own data
POST/api/gdpr/delete-requestAuthenticated user; deletion request, not immediate deletion

Stripe webhooks are integration endpoints with signature verification, not dashboard-session operations. Processing claims have reclaimable five-minute owner-scoped leases: completed duplicates return success, while an in-flight claim returns 503 with Retry-After. Claims fence completion ownership, not exactly-once external side effects; handlers must remain idempotent. Operational seed/cleanup endpoints are not ordinary customer workflows; consult source and environment guards before use.

Known Client Gaps

Assets and audit views receive the active organization ID. Stripe returns to /billing, which resolves to the dashboard billing tab. Assets remain stored records rather than live infrastructure provisioning.