Distributor API v1

Distributor API v1 is SMAO's maintained Distributor API. Synaxon and other distribution partners use it at /api/distributor/v1 to manage a partner-based reseller hierarchy and retrieve data for external billing.

The provisioning model

The API manages a three-tier hierarchy with an explicit partner resource:

Distributor
  -> Partner (MSP)
      -> Customer organization

• Partners are created through /partners. Each partner gets its own internal SMAO organization, returned as partner.organizationId, and can onboard customers from the dashboard.
• Customer organizations use partnerId to link to their MSP and externalCustomerId as the distributor's reconciliation identifier.
• Plans are assigned directly per organization through PATCH /organizations/{organizationId}/plan.

Authentication and behavior

Send the SMAO-issued v1 key as Authorization: Bearer <key>. Keys include the partner, organization, and usage permissions documented for each endpoint. Invalid version metadata returns 403 API_VERSION_NOT_ALLOWED.

Errors use the flat { "status": "error", "errorCode", "message" } envelope. The requests-per-minute limit is configured per key and defaults to 60. See Authentication and Errors.

Integration is polling-based; there are no Distributor webhooks.

Operational boundaries

• /organizations manages end-customer organizations linked to a partner. The MSP's internal organization is identified by partner.organizationId and is not a customer resource.
• Partner creation attempts to start the MSP organization on a free trial when a trial plan is available. Trial setup is best-effort. The trial is capped by call minutes, not by time; to keep the MSP's own workspace in use beyond it, assign a paid plan with PATCH /partners/{partnerId}/plan - the MSP organization cannot be reached through /organizations/{organizationId}/plan.
• When contactEmail is supplied, invitation creation and email delivery are best-effort. Reconcile dashboard access separately after provisioning.
• A partner with an internal MSP organization cannot be deleted through DELETE /partners/{partnerId} while that organization exists. There is no cascade-delete operation.

API reference

Start with the v1 quickstart. The reference below is generated from the v1 OpenAPI spec. The raw spec is served at SMAO_API_URL/api/distributor-docs/v1/openapi.yaml. The bare /api/distributor-docs/openapi.yaml path serves the same contract for saved integrations.