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.