v1 Quickstart

This is the restored partner-based workflow for Synaxon and existing v1 integrations. Production base URL: https://api.smao.ai/api/distributor/v1. For the development environment use https://api2.smao.ai/api/distributor/v1.

1. Configure the v1 key

Distributor keys are issued by SMAO and shown only once. Store the raw key in a secret manager. A v1 key is authorized for v1 only.

export SMAO_DISTRIBUTOR_KEY="your-v1-distributor-key"
export BASE="https://api.smao.ai/api/distributor/v1"

GET /health is public. All other endpoints require the Bearer token:

curl "$BASE/health"
curl "$BASE/plans" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY"

Choose a plan slug and commitment from /plans for the customer request below.

2. Create the partner (MSP)

curl -X POST "$BASE/partners" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MSP Hamburg GmbH",
    "externalPartnerId": "SYN-MSP-001",
    "contactEmail": "[email protected]",
    "contactName": "Ada Admin",
    "timezone": "Europe/Berlin"
  }'

Save both IDs from the response:

• partner.id is the partnerId used for customer organizations.
• partner.organizationId is the MSP's own internal SMAO organization.

The internal organization is part of successful partner provisioning. Trial setup, invitation creation, and invitation email delivery are best-effort; do not use email receipt as the provisioning acknowledgement.

3. Create a customer organization

curl -X POST "$BASE/organizations" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": {
      "name": "Customer Hamburg GmbH",
      "industry": "Manufacturing",
      "timezone": "Europe/Berlin"
    },
    "owner": {
      "email": "[email protected]",
      "firstName": "Chris",
      "lastName": "Customer"
    },
    "externalCustomerId": "SYN-CUSTOMER-4711",
    "externalContractId": "SYN-CONTRACT-4711",
    "partnerId": "665abc123def456789012345",
    "plan": {
      "slug": "business",
      "commitment": "monthly"
    }
  }'

Replace partnerId and the plan values with those returned by your calls. A successful response includes the customer organization and its owner invitation record. Email transport is best-effort.

externalPartnerId and externalCustomerId are reconciliation keys. If a retry returns a duplicate-ID conflict, fetch the existing record instead of creating a different identifier.

4. Read usage and billing

Usage query windows use inclusive YYYY-MM-DD dates and may cover up to 365 days. For compatibility, the single-organization response serializes its period boundaries as ISO UTC date-times; aggregate responses echo the query dates.

curl "$BASE/organizations/69c175970f3e28310926a1aa/usage?from=2026-07-01&to=2026-07-31" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY"

curl "$BASE/partners/665abc123def456789012345/usage?from=2026-07-01&to=2026-07-31" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY"

Billing summaries are limited to 31 days and price usage against the current assigned plan:

curl "$BASE/organizations/69c175970f3e28310926a1aa/billing-summary?from=2026-07-01&to=2026-07-31" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY"

Monetary values are in the smallest unit of the returned currency (for example, cents for EUR). The API is polling-only; there are no Distributor webhooks.