API Documentation

Backend REST API Reference

Complete documentation of HTTP endpoints, authentication schemas, request bodies, and JSON response models for developer integration and platform extensions.

🔑 Authentication & Headers

Authenticated endpoints require an HTTP Authorization header containing the JSON Web Token returned upon login or registration:

Authorization: Bearer <YOUR_JWT_TOKEN> Content-Type: application/json Accept: application/json

1. Authentication Endpoints (/api/auth/*)

POST/api/auth/register
Public

Register a new user account with email, username, and password.

Request Body:
{ "email": "alex@example.com", "username": "alex99", "password": "Password123!", "name": "Alex", "gender": "male", "country": "US" }
Response (200 OK):
{ "token": "eyJhbGciOi...", "user": { "id": "usr_...", "username": "alex99", "name": "Alex", "gems": 100, "isVip": false } }
POST/api/auth/login
Public

Authenticate existing user via credentials.

Request Body:
{ "email": "alex@example.com", "password": "Password123!" }
Response (200 OK):
{ "token": "eyJhbGciOi...", "user": { "id": "usr_...", "username": "alex99", "name": "Alex", "gems": 100 } }
POST/api/auth/firebase
Public

Authenticate with a Firebase ID token (Google Sign-In or Phone SMS login).

Request Body:
{ "idToken": "firebase_jwt_id_token_from_client_sdk" }
Response (200 OK):
{ "token": "eyJhbGciOi...", "user": { "id": "usr_...", "username": "google_user", "name": "Google User" } }
POST/api/auth/guest
Public

Instantly provision a temporary guest account for rapid trial matchmaking.

Response (200 OK):
{ "token": "eyJhbGciOi...", "user": { "id": "guest_182746", "username": "guest_182746", "isGuest": true, "gems": 30 } }
GET/api/auth/me
User JWT

Fetch current authenticated user profile, wallet balance, and VIP status.

2. Payments & Monetization Endpoints (/api/payments/*)

GET/api/payments/packages
Public

Retrieve configured diamond coin packages with prices and bonus amounts.

Response (200 OK):
[ { "id": "pkg_100", "diamonds": 100, "bonus": 10, "price": 1.99, "currency": "USD" }, { "id": "pkg_500", "diamonds": 500, "bonus": 75, "price": 7.99, "currency": "USD" } ]
POST/api/payments/native/verify
User JWT

Validate Google Play Billing or Apple StoreKit receipts server-side (Fail-closed validation).

Request Body:
{ "platform": "google" | "apple", "productId": "diamonds_500", "receipt": "..." }
Response (200 OK):
{ "success": true, "diamondsCredited": 575, "newBalance": 725 }
POST/api/payments/stripe/create-checkout
User JWT

Create a Stripe Checkout Session for web diamond coin purchases.

3. Virtual Gifts & VIP Memberships

GET/api/gifts
Public

Retrieve available animated gifts with their diamond coin costs.

Response (200 OK):
[ { "id": "rose", "name": "Red Rose", "coinPrice": 10, "icon": "/images/gifts/rose.png" }, { "id": "sports_car", "name": "Super Car", "coinPrice": 500, "icon": "/images/gifts/car.png" } ]
POST/api/gifts/send
User JWT

Send a virtual gift to a partner during a live call or direct chat (deducts diamonds from sender).

Request Body:
{ "receiverId": "usr_target_id", "giftId": "rose" }
GET/api/vip/plans
Public

Fetch available VIP subscription durations (e.g., 7 days, 30 days, 365 days).

4. WebRTC Infrastructure & Settings

GET/api/webrtc/ice-servers
Public

Returns dynamic STUN and TURN ICE server configurations for WebRTC video peers.

Response (200 OK):
{ "iceServers": [ { "urls": "stun:stun.l.google.com:19302" }, { "urls": "turn:turn.example.com:3478", "username": "user", "credential": "pass" } ] }
GET/api/init
Public

Client application initialization payload (app name, logo URL, terms URL, enabled auth methods).

5. Administrative Management API (/api/admin/*)

POST/api/admin/login
Public

Admin authentication with username & password (returns admin JWT).

GET/api/admin/stats
Admin Only

Real-time platform metrics (active calls, online users, total registered accounts, gross revenue).

GET/api/admin/users
Admin Only

Paginated user management list with search, filter, ban status, and wallet balance.

POST/api/admin/users/:id/ban
Admin Only

Toggle ban status for a user to immediately revoke access.