Skip to main content

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.

Back to top