BEX Reseller REST API Specification & OAuth Authentication

1. Overview & API Design Philosophy #

The BEX Reseller REST API provides a high-throughput, enterprise-grade integration interface that enables master distributors, ISVs, and custom billing portals to programmatically manage bandwidth allocations, sub-reseller hierarchies, client provisioning, and real-time usage telemetry. Built on strict RESTful principles, JSON payload schemas, and zero-trust security standards, the API enables white-label integration into existing ERP, CRM, and custom mobile/web applications.

2. Authentication, OAuth2 Framework & Scoped JWTs #

To guarantee secure machine-to-machine (M2M) communication without exposing master credentials, BEX implements an RFC 6749-compliant OAuth2 Client Credentials framework:

• Client Credentials Grant: Integrations authenticate using an isolated client_id and client_secret pair generated via the BEX portal.
• Scoped Short-Lived JWTs: Successful authentication returns a JSON Web Token (JWT) signed via RS256 algorithm with a maximum lifetime of 60 minutes.
• Granular Scope Isolation: Token access permissions are governed by explicit scopes:
  • reseller:read — View balances, tiers, and telemetry.
  • subreseller:manage — Create, modify, or suspend child reseller nodes.
  • tokens:allocate — Execute token balance transfers between accounts.
  • users:provision — Issue, configure, and revoke client VPN credentials.

3. Core RESTful Endpoints & Payload Specifications #

The API exposes versioned JSON endpoints (/api/v1/) with strict HTTP verbs and standardized error responses:

• Authentication Endpoint (POST /api/v1/auth/token): Exchanges API credentials for a scoped JWT bearer token.
• Provision Sub-Account (POST /api/v1/reseller/sub-accounts): Creates child reseller nodes or client accounts under the authenticated master account:
  {“name”: “Enterprise Sub-Node Alpha”, “tier_id”: “tier_gold_02”, “initial_credit_gb”: 5000, “scoped_permissions”: [“users:provision”, “tokens:allocate”]}
• Allocate Token Credit (POST /api/v1/tokens/allocate): Executes atomic token pool transfers from master balance to sub-accounts:
  {“target_account_id”: “acc_sub_892301”, “amount_tokens”: 1000, “reference_note”: “Invoice-2026-09-001”}
• Query Real-Time Usage (GET /api/v1/analytics/usage): Returns aggregated eBPF bandwidth consumption metrics filtered by date range or tunnel ID.

4. Rate-Limiting, Idempotency & Webhook Callbacks #

To protect API gateway availability and prevent financial duplication during network retries, BEX enforces strict runtime safeguards:

• Header-Based Rate Limiting: Gateway instances evaluate request volume using a Redis-backed Sliding Window algorithm. Headers return real-time quota state:
  • X-RateLimit-Limit: 1000
  • X-RateLimit-Remaining: 842
  • X-RateLimit-Reset: 1758882000
• Idempotent Token Operations: All credit mutation calls require an X-Idempotency-Key HTTP header. Duplicate requests returning identical keys replay cached HTTP responses without re-executing balance deductions.
• Asynchronous Webhook Callbacks: High-frequency events (token.threshold.low, session.terminated, subreseller.created) dispatch HMAC-SHA256-signed JSON webhooks to partner endpoints with automatic retry backoffs.

5. Key Strategic Benefits #

• Seamless ERP/CRM Integration: Enables fully automated billing and provisioning without human intervention.
• Zero-Trust Security: Short-lived scoped JWTs prevent privilege escalation or long-term credential leakage.
• Financial Replay Protection: Idempotency keys eliminate double-crediting risks during network drops.