WWorkbase
Create account

API

API structure, authentication modes, and reference links.

Workbase exposes multiple HTTP API surfaces with different audiences and stability expectations.

API families

Versioned API (/api/v1/*)

Primary stable JSON API for core resources:

  • products, categories, manufacturers
  • options, option values, product options, price tiers
  • countries, counterparties, currencies, orders
  • files, upload, account settings, system endpoints

OpenAPI coverage is maintained for this family.

Storefront API (/api/storefront/*)

Storefront-facing endpoints for:

  • catalog/category/product resolution
  • pricing quotes
  • OTP auth and customer account session
  • storefront pages/blogs/product lists
  • checkout/order placement

These routes are not currently part of public/openapi.json.

Admin/module API (/api/admin/*)

Admin operations and module workflows:

  • module enable/disable and module-specific CRUD/actions
  • integration sync/import/export controls
  • admin settings and danger-zone operations

These routes are also not part of public/openapi.json.

Authentication modes

resolveActor() supports:

  • session auth (NextAuth cookie)
  • Basic auth (Authorization: Basic ...)
  • Bearer auth (Authorization: Bearer ..., API keys)

For session-based non-GET/HEAD requests, API requires CSRF token (x-csrf-token).

Envelope conventions

Most APIs return a consistent envelope:

  • success: { data, meta, error: null }
  • error: { data: null, meta: null, error: { code, message, ... } }

/api/v1 middleware behavior

proxy.ts applies to /api/v1/*:

  • CORS checks via API_ALLOWED_ORIGINS
  • in-memory rate limiting via API_RATE_LIMIT
  • preflight handling for OPTIONS

Idempotency support

Some mutating flows use Idempotency-Key persistence (IdempotencyKey table, 24h TTL) via withIdempotency().

API references