# Distributor API v1 (https://docs2.smao.ai/docs/distributor-v1)



Distributor API v1 lets distributors manage the partners (MSPs) they resell
SMAO through, those partners' customer organizations, their plans, and the
usage you invoice. Base path: `/api/distributor/v1`.

## The provisioning model [#the-provisioning-model]

```text
Distributor
  -> Partner (MSP)
      -> Customer organization
```

* Create partners through `/partners`. Each partner gets its own SMAO
  organization, returned as `partner.organizationId`, and can onboard
  customers from the dashboard.
* Customer organizations link to their MSP with `partnerId` and carry your
  `externalCustomerId` for reconciliation.
* Assign plans per organization with
  [`PATCH /organizations/{organizationId}/plan`](/docs/distributor-v1/billing/updateDistributorOrganizationPlan).

## Authentication and behavior [#authentication-and-behavior]

Send the SMAO-issued key as `Authorization: Bearer <key>`. Errors use the flat
`{ "status": "error", "errorCode", "message" }` envelope. Each key has a
per-minute limit, 60 requests by default. See
[Authentication](/docs/authentication) and [Errors](/docs/errors).

There are no Distributor webhooks; poll for changes.

## Things to know [#things-to-know]

* `/organizations` covers customer organizations only. The MSP's own
  organization is not reachable there; assign its plan with
  `PATCH /partners/{partnerId}/plan`.
* Creating a partner also tries to start a trial and, when `contactEmail` is
  given, to send an invitation. Neither is guaranteed, so check dashboard
  access afterwards.
* A partner cannot be deleted while it has customer organizations or its MSP
  organization. There is no cascade delete.

## API reference [#api-reference]

Start with the [quickstart](/docs/distributor-v1/quickstart). The reference
below is generated from the OpenAPI spec, which is served at
[**SMAO\_API\_URL**/api/distributor-docs/v1/openapi.yaml](https://api2.smao.ai/api/distributor-docs/v1/openapi.yaml).