Purpose./api/v1 serves integrations, webhooks and future clients. Server Components and Server Actions serve the browser UI; this API is a parallel surface that enforces the same tenant, role, scope and step-up rules.
Protocol. HTTPS, JSON request and response bodies (application/json; charset=utf-8), except:
GET /api/v1/openapi returns a raw OpenAPI document (no envelope).
GET /api/v1/health returns HTML when the client sends Accept: text/html.
/api/v1/auth/* returns Better Auth's own JSON, not the DFFMS envelope.
POST /api/v1/webhooks/{provider} accepts provider payloads (JSON, or form-encoded for Twilio; the route itself reads the raw body).
Tenancy. Business data is tenant-scoped. Most routes take the tenant from the X-DFFMS-Tenant-Id header (UUID). Some routes (reporting, marketplace decision, push subscriptions) do not read this header; see Section 2.3.
Data model conventions.
Money is a string of integer minor units (for NGN, kobo), for example "2500000" for NGN 25,000.00. Currency is an ISO 4217 code in uppercase.
Database bigint values are serialised as decimal strings.
Dates are YYYY-MM-DD; timestamps are ISO 8601 with offset.
Background processing. Provider calls and report generation run asynchronously through a transactional outbox (see Section 8).