# 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.