PayOsOne REST API

The existing web application keeps working unchanged through the platform SDK. External apps go through the REST API. Both share exactly one database.

All requests are POST to a single gateway endpoint, with the HTTP method and path described in the JSON body:

POST https://dnx-pulse-os.base44.app/functions/payosoneApi

{
  "method": "GET",
  "path":   "/v1/businesses",
  "query":  { "limit": 20 },
  "body":   { },            // for POST/PUT
  "apiKey": "pyo_live_..."  // or use the Authorization header
}

Alternatively pass the key via a header: Authorization: Bearer pyo_live_…

Every request (except /v1/health) requires a valid API key. Keys are issued by a PayOsOne admin from the panel below. The raw key is shown once at creation; only its SHA-256 hash is stored. Keys carry scopes and may be scoped to a single business (business_id) or platform-level (blank) for cross-business access.

A scoped key (with a business_id) only ever sees its own business's records — enforced server-side.

Each key is limited to 120 requests per 60 seconds by default (configurable per key). Exceeding it returns 429 rate_limited.

All errors use a consistent shape:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Missing required scope: businesses:write"
  }
}

Status codes: 400 validation, 401 auth, 403 scope/tenant, 404 route/resource, 429 rate limit, 500 server.

Every API call is recorded in the AuditLog entity with the key name, method, path and severity. Denied calls (missing scope) are logged at warning severity.

curl -X POST https://dnx-pulse-os.base44.app/functions/payosoneApi \
  -H "Authorization: Bearer pyo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "method": "GET", "path": "/v1/businesses", "query": { "limit": 5 } }'

→ 200
{
  "data": [ { "id": "...", "business_name": "...", "tenant_id": "TEN-..." } ],
  "count": 1,
  "limit": 5
}