# Distributor API v1 (https://docs.smao.ai/docs/distributor-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-provisioning-model]

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

```text
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`](/docs/distributor-v1/billing/updateDistributorOrganizationPlan).

## Authentication and behavior [#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](/docs/authentication) and [Errors](/docs/errors).

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

## Operational boundaries [#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 [#api-reference]

Start with the [v1 quickstart](/docs/distributor-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](https://api.smao.ai/api/distributor-docs/v1/openapi.yaml).
The bare `/api/distributor-docs/openapi.yaml` path serves the same contract for
saved integrations.