Distributor API v1

Distributor API v1 is the supported compatibility contract restored for Synaxon and other existing partner-based integrations. It remains available at /api/distributor/v1 and is regression-tested so those integrations can keep running. New capabilities are not added to v1.

Every new distributor integration should use the organization-centric Distributor API v2. Both versions run in parallel; v1 is not being redirected to v2 and existing consumers are not forced to migrate.

The provisioning model

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

Distributor
  -> Partner (MSP)
      -> Customer organization

• Partners (MSPs) are created via the /partners endpoints. Each partner gets its own internal SMAO organization, returned as partner.organizationId, and the MSP can onboard customers from the SMAO dashboard without further API calls.
• Customer organizations are created with a partnerId linking them to their MSP, plus your own externalCustomerId.
• Plans are assigned directly per organization (PATCH /organizations/{organizationId}/plan) — there are no license objects in v1.

Authentication and behavior

Send the SMAO-issued v1 key as Authorization: Bearer <key>. v1 keys include the partner permissions needed by /partners in addition to organization and usage permissions. A key is authorized for one Distributor API version; cross-version calls return 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 webhooks in either version.

Compatibility boundaries

• /organizations manages end-customer organizations linked to a partner. The MSP's internal organization is identified through partner.organizationId, not treated as a customer resource.
• Partner creation attempts to start the internal MSP organization on a free trial when a trial plan is available. Trial setup is best-effort and is not part of the partner-creation success guarantee.
• When contactEmail is supplied, invitation creation and email delivery are best-effort. Reconcile dashboard access separately after provisioning.
• A normally provisioned partner has an internal MSP organization and therefore cannot be deleted through DELETE /partners/{partnerId} while that organization exists. There is no cascade-delete operation for a partner.

API reference

Start with the v1 quickstart. The endpoint reference below is generated from the restored v1 OpenAPI spec. The raw spec is served at api.smao.ai/api/distributor-docs/v1/openapi.yaml; the bare /api/distributor-docs/openapi.yaml path serves the same v1 contract for compatibility.