Partner API authentication lets approved partners call Onyx APIs from a trusted server.
Use it to browse approved catalogue packages, create orders, retrieve order state, check usage, review ledger activity, manage invoices, configure webhooks, and replay eligible events.
Partner credentials are server-side credentials. They are not user tokens and they must never ship inside a browser, mobile app, public repository, analytics tool, or customer support transcript.
Credentials
A partner credential identifies an approved organization and the scopes Onyx has granted to that organization.
Credentials can be:
- active
- rotated
- revoked
Rotate credentials when a team member leaves, a secret may have been exposed, or your security policy requires scheduled rotation.
Scopes
Scopes limit what a credential can do.
Approved scopes can cover catalogue access, order creation, order lookup, usage lookup, ledger review, invoice review, webhook management, and event replay.
Request the smallest scope set that lets your integration work. Do not use broad credentials for support tools, analytics jobs, or local development when a narrower credential is enough.
Sandbox And Live Access
Sandbox access lets your team test integration behavior before live launch.
Use sandbox to validate catalogue display, order creation, idempotency, webhook handling, support intake, billing reconciliation, and failure recovery.
Live access allows real customer orders and real service preparation. Move to live only after your launch checklist, privacy review, support path, and webhook handling are approved.
Server-Side Requests
Call partner APIs from your server.
Your server should attach the approved credential, set an idempotency key for order-creating actions, store the partner order reference, and record the response state returned by Onyx.
Client apps should call your server, not the Onyx partner API directly.
Idempotency
Use idempotency for order creation and other actions that should not run twice.
An idempotency key protects the customer when a request times out, a retry occurs, or a network issue interrupts the response. Reuse the same key only for the same action with the same request body.
Do not generate a new key when retrying the same order after a timeout.
Safe Logging
Partner logs should help your team debug without exposing sensitive material.
Log request timing, public order references, status codes, reason codes, and safe error summaries. Do not log credentials, activation material, webhook secrets, full payloads, private customer data, or customer payment details.
Credential Loss
If a credential may be exposed, revoke or rotate it immediately.
After rotation, update your server configuration, confirm webhook delivery still works, and review recent activity for unexpected requests.