Benji Pays Organizations API

openapi: 3.2.0
info:
  title: Benji Pays Partner Organizations API
  description: 'The Benji Pays Partner API is a JSON over HTTPS API. All endpoints live under `/v2`. Errors follow RFC 7807 and are served as `application/problem+json`. This overview describes the cross-cutting behavior shared by every partner endpoint. Endpoint-specific schemas live with each operation. ## Authentication


    Partner endpoints authenticate with an Auth0 M2M access token in the `Authorization` header:


    ```

    Authorization: Bearer

    ```


    Tokens are obtained from Auth0 with the OAuth 2.0 client-credentials grant against the `https://api.benjipays.com` audience. The token''s actor claim (`distributor`, `partner`, or `organization`) and OAuth scopes determine which routes the caller can reach. Failures return `401 Unauthorized` (missing/expired/invalid credentials) or `403 Forbidden` (wrong actor type or missing scope). ## Request and Correlation IDs


    Two header pairs help with tracing:


    | Header | Direction | Purpose |

    | --- | --- | --- |

    | `X-Request-ID` | request (optional) / response (always) | Unique identifier for one request. Generated as a UUID v4 when the client omits it. |

    | `X-Correlation-ID` | request (optional) / response (always) | Identifier that flows across service boundaries for distributed tracing. Generated as a UUID v4 when omitted. |


    Both IDs are echoed on success and included as `requestId` / `correlationId` extensions on `application/problem+json` error responses. These headers are auto-injected on every operation in this spec — do not redeclare them per route. ## Idempotency


    POST, PATCH, and PUT endpoints accept an `Idempotency-Key` header to make retries safe. - Format: 1–255 characters, alphanumeric only (`[a-zA-Z0-9]+`). - Scope: keys are scoped per actor (no cross-tenant collisions). - Cache: the first response for a given key is cached for 24 hours. - Replay: a duplicate request with the same key and the same body returns the cached response with `X-Idempotency-Replayed: true` only after credentials were resolved by the global authenticate middleware (API key or Auth0 JWT signature check) before the idempotency cache lookup. - Conflict: same key with a different body returns `409 Conflict`. - In-flight: a second request with the same key while the first is still being processed returns `429 Too Many Requests` with `Retry-After` and problem `type` `https://api.benjipays.com/problems/idempotency-processing` (distinct from rate-limit `…/rate-limit-exceeded`). `Idempotency-Key` is auto-injected on every POST/PATCH/PUT operation in this spec — do not redeclare it per route. Routes that intentionally opt out set `x-bp-skip-idempotency: true`. The middleware fails open: if the cache layer is unavailable the request proceeds without idempotency protection. ## Pagination


    List endpoints use offset-based pagination with two query parameters:


    | Parameter | Type | Default | Bounds |

    | --- | --- | --- | --- |

    | `limit` | integer | `20` | `1`–`1000` |

    | `offset` | integer | `0` | `≥ 0` |


    Some endpoints use different bounds (for example usage/billing and autoprocessing forecast). Check the per-operation schema. Responses follow this envelope:


    ```json

    {

    "data": [ /* items */ ],

    "pagination": {

    "limit": 20,

    "offset": 0,

    "hasMore": true,

    "nextOffset": 20,

    "prevOffset": null

    }

    }

    ```


    Many list endpoints also include `pagination.total` (count of matching items across all pages). Per-operation response schemas are authoritative. Use `hasMore` to decide whether to fetch another page and `nextOffset` for the next request rather than computing it on the client. ## Dates and Times


    All **response** timestamps are ISO-8601 strings in UTC (for example `2024-01-01T12:00:00.000Z`). Date-range **query** parameters support two input modes where the endpoint accepts them:


    | Input format | Interpretation |

    | --- | --- |

    | `YYYY-MM-DD` (calendar day) | Full day in **UTC**. Start = `00:00:00.000Z`, end = `23:59:59.999Z` on that date. Same start and end day returns the full UTC day. |

    | ISO-8601 UTC timestamp (e.g.'
  version: 2.0.0
  contact:
    name: Benji Pays API Support
    email: benji@benjipays.com
servers:
- url: https://api.benjipays.com
  description: Development server
security:
- BearerAuth: []
tags:


# --- truncated at 32 KB (102 KB total) ---
# Full source: https://artifacts.apis.io/benjipays-com/openapi/benjipays-com-organizations-api-openapi.yml