REST API Overview

The CMS exposes a REST API that mirrors all major platform functions, allowing administrators, partners, and developers to automate operations.

API Design Principles

• Standards-Based: JSON over HTTPS, aligned with REST conventions.

• Role-Aware: All calls are scoped to the authenticated user’s role (Platform, Distributor, Partner, Tenant).

• Secure by Default: Requires bearer tokens obtained through login or federation flows.

• Consistent Resources: Entities in the API (Distributors, Partners, Tenants, Subscriptions, Usage, Billing, Commissions) align directly with portal objects.

Authentication

• Login Flow: Obtain a token via the /api/v1/auth/login endpoint.

• Federated Tokens: Forward Microsoft Entra or Google tokens for verification at /api/v1/auth/federated.

• Token Lifetime: Tokens are time-bound; refresh before expiry to avoid failures.

Core Endpoints

• Distributors & Partners

  • /api/v1/distributors – create, list, and manage distributors

  • /api/v1/partners – create, list, and manage partners

• Tenants & Subscriptions

  • /api/v1/tenants – onboard tenants, assign admins

  • /api/v1/subscriptions – create and manage subscriptions

• Plans & Pricing

  • /api/v1/plans – publish and update plans

  • /api/v1/pricing – define SKUs, rates, and thresholds

• Usage & Billing

  • /api/v1/usage – ingest usage data

  • /api/v1/billing/summary – generate subscription and tenant billing summaries

• Commissions

  • /api/v1/commissions/summary – calculate and retrieve commissions for partners and distributors

• System & Identity

  • /api/v1/settings – update branding, licensing, and identity configs

  • /api/v1/roles – assign or update user roles

Typical Automation Scenarios

• Tenant Onboarding
  Automate tenant creation, subscription assignment, and role setup via API.

• Usage Ingestion
  Post usage records into /api/v1/usage on a scheduled job (e.g., nightly processing per region).

• Billing Automation
  Trigger invoice generation and retrieve billing summaries at end-of-month.

• Commission Reconciliation
  Automate pulling /commissions/summary for financial reporting and payouts.

• Integration with External Systems

  • Connect billing output to finance/ERP systems.

  • Forward alerts or health checks to monitoring solutions.

  • Sync user identity with corporate directories.

Developer Notes

• Full Swagger documentation is bundled with the CMS at /swagger.

• API clients can be generated automatically from the provided swagger.json.

• Rate limits apply to protect system performance; batch operations where possible.