Guides
  1. getting-started

Getting Started

A 5-minute overview of the Benji Pays Partner API for new integrators.

The Benji Pays Partner API is a JSON-over-HTTPS API. All endpoints live under /v2, all error responses follow RFC 7807, and all cross-cutting behavior is identical across endpoints.

What this API is for

The API exposes the Benji Pays platform to two audiences:

  • Distributor and partner integrations (e.g. marketplaces, MSP tooling) authenticate with an Auth0 M2M token and operate on resources tied to their actor.
  • Merchant-facing integrations (per-organization) authenticate with an x-api-key issued from the merchant app and act on behalf of a single organization.

Both authentication flows use the same routes and share the same cross-cutting behavior (request IDs, idempotency, pagination, rate limits, errors).

Before you start

You need:

  • An x-api-key issued from the merchant app, or Auth0 M2M client_id/client_secret for programmatic access.
  • An HTTP client that can send custom headers (x-api-key, Authorization, Idempotency-Key, X-Request-ID, etc.).

A typical first call

After exchanging your Auth0 credentials for an access token (see Authentication), call GET /v2/whoami to confirm the token's actor and scopes:

curl -X GET https://api.benjipays.com/v2/whoami \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

A successful response returns the resolved actor and the scopes you have:

{
  "actor": {
    "type": "partner",
    "actor_id": "bp-actor-123"
  },
  "permissions": [
    "partners:accounts:read",
    "partners:subscriptions:read"
  ],
  "message": "hello from api /v2/whoami"
}

What to read next

Each cross-cutting topic has its own guide:

  • Authentication — Auth0 M2M tokens and the x-api-key flow.
  • Rate Limits — sliding-window limits and the X-RateLimit-* headers.
  • Idempotency — making POST/PATCH/PUT safe to retry.
  • Request Tracing — X-Request-ID and X-Correlation-ID.
  • Pagination — offset-based pagination and response envelope.
  • Errors — RFC 7807 problem details and common status codes.

The per-endpoint reference is generated from the OpenAPI specs at /docs/bp-api-openapi-partner.{json,yaml} (Auth0 M2M / partner endpoints) and /docs/bp-api-openapi-merchant.{json,yaml} (x-api-key / merchant endpoints).