ONYX
Docs

Partner API Reference

Use the Partner API endpoint map, authentication model, response envelope, errors, idempotency, and rate limits.

Partner API gives approved partners server-side access to Onyx Partner Platform.

Use it to read the approved catalogue, create orders, retrieve order state, review active services, check usage, reconcile billing records, manage webhook endpoints, and replay eligible events.

Keep Partner API calls on your server. Your browser app or mobile app should call your own server, and your server should call Onyx.

Authentication

Authenticate each request with one approved partner credential.

Supported credential headers are:

  • x-onyx-partner-api-key
  • x-api-key
  • Authorization

Protect credentials as secret material. Do not place them in client-side code, public repositories, analytics tools, support tickets, screenshots, or customer-visible logs.

Response Envelope

Successful responses return a data object.

{
  "data": {}
}

Errors return an error object.

{
  "error": {
    "code": "invalid_request",
    "message": "Request body must be an object"
  }
}

Idempotency

Use an idempotency key for order creation.

Send the key with idempotency-key or x-idempotency-key. Reuse the same key only when retrying the same request body for the same customer action.

Do not generate a new key for a retry after a timeout.

Rate Limits

Partner API applies separate read and write limits.

Default read limit is 240 requests per minute. Default write limit is 60 requests per minute. A rate-limited response returns 429 and a retry-after header when retry timing is available.

Endpoint Map

| Area | Method | Path | | --- | --- | --- | | Catalogue | GET | /v1/partner/catalog/packages | | Catalogue | GET | /v1/partner/catalog/packages/{packageId} | | Orders | POST | /v1/partner/orders | | Orders | GET | /v1/partner/orders/{orderId} | | Services | GET | /v1/partner/esims | | Services | GET | /v1/partner/esims/{iccid} | | Usage | GET | /v1/partner/esims/{iccid}/usage | | Billing | GET | /v1/partner/ledger/transactions | | Billing | GET | /v1/partner/invoices | | Webhooks | GET | /v1/partner/webhook-endpoints | | Webhooks | POST | /v1/partner/webhook-endpoints | | Webhooks | POST | /v1/partner/webhook-endpoints/{endpointId}/rotate-secret | | Events | GET | /v1/partner/webhook-events | | Events | POST | /v1/partner/webhook-events/{eventId}/replay |

Safe Logging

Log request timing, public order references, status codes, reason codes, and safe summaries.

Do not log credentials, activation material, webhook signing secrets, full payloads, private customer data, customer payment details, or private Onyx account information.