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
| Method | Path | Access / behavior |
|---|---|---|
| GET | /api/health | Health 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/:invitationId | Public id, role, status, expiry; no recipient email or org name |
| POST | /api/contact | Public validated contact intake |
| POST | /api/newsletter | Public 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.
| Method | Path | Required access |
|---|---|---|
| GET, POST | /api/orgs | Platform super-admin plus system-org membership |
| GET, POST | /api/orgs/:orgId/members | Org owner/admin or platform super-admin |
| PUT | /api/orgs/:orgId/members/:userId/role | Org owner/admin or platform super-admin; cannot change own role |
| DELETE | /api/orgs/:orgId/members/:userId | Org owner/admin or platform super-admin; cannot remove self; account preserved |
| GET | /api/orgs/:orgId/invitations | Org owner/admin or platform super-admin |
| DELETE | /api/orgs/:orgId/invitations/:invitationId | Org owner/admin or platform super-admin |
| GET | /api/orgs/:orgId/assets | Org member or platform super-admin |
| GET | /api/orgs/:orgId/assets/:assetId | Org member or platform super-admin |
| POST | /api/orgs/:orgId/assets | Org owner/admin or platform super-admin |
| PUT, DELETE | /api/orgs/:orgId/assets/:assetId | Org 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
| Method | Path | Required access / behavior |
|---|---|---|
| GET | /api/orgs/billing/categories | Authenticated session; active categories |
| GET | /api/orgs/billing/categories/:id/products | Authenticated session; products/prices |
| GET | /api/orgs/billing/products/:id | Authenticated session; product details |
| GET | /api/orgs/billing/packages | Authenticated session; package components |
| POST | /api/orgs/billing/sync-catalog | Platform super-admin plus system-org membership |
| GET | /api/orgs/:orgId/available-plans | Org member or platform super-admin; recurring plans |
| GET | /api/orgs/:orgId/subscription | Org member or platform super-admin; legacy latest-subscription view |
| GET | /api/orgs/:orgId/subscriptions | Org member or platform super-admin; subscriptions with items |
| GET | /api/orgs/:orgId/invoices | Org member or platform super-admin; paginated Stripe invoices |
| GET | /api/orgs/:orgId/payment-method | Target org owner/admin membership |
| POST | /api/orgs/:orgId/checkout | Target org owner/admin membership; Stripe Checkout URL |
| POST | /api/orgs/:orgId/portal | Target org owner/admin membership; Stripe Portal URL |
| POST | /api/orgs/:orgId/add-addon | Target org owner/admin membership |
| DELETE | /api/orgs/:orgId/add-on/:itemId | Target 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.
The identifiers above are placeholders, not recorded API results.
Platform Administration and Account Data
| Method | Path | Required access |
|---|---|---|
| GET | /api/admin/users | Platform admin/operator |
| POST | /api/admin/users | Platform admin |
| PUT | /api/admin/users/:id/role | Platform admin |
| DELETE | /api/admin/users/:id | Platform admin |
| GET | /api/admin/audit-logs | Platform admin/operator; filters/pagination |
| GET | /api/gdpr/export | Authenticated user; own data |
| POST | /api/gdpr/delete-request | Authenticated 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.