Video Architecture

Three-Tier Architecture Model

The EnableX Video platform is organized into three tiers: your app server, the EnableX Video API, and the EnableX media infrastructure. Understanding this separation is key to building robust video applications.

Your App Server (holds App ID + App Key)
    | creates rooms, issues tokens
    | receives webhooks, retrieves post-session data
    | HTTPS only, backend only
    |
EnableX Video API (api.enablex.io/video/v2)
    | REST API, HTTP Basic Auth
    | room provisioning, token issuance, CDR retrieval
    |
    |-- Signalling Path (WSS)
    |   EnableX Signalling Servers
    |   (ICE negotiation, SDP exchange)
    |
    +-- Media Path (WebRTC/RTP)
        EnableX Media Servers (SFU/MCU)
        (codec negotiation, media forwarding, recording)
        |
        v
Client (Browser/Mobile, runs SDK)
    | has token (no App Key)
    | initiates WebRTC connection
    | sends/receives media

Tier 1: Your App Server

Your backend application is the source of truth for user identity, permissions, and business logic.

Responsibilities:

• Credential storage: Stores your App ID and App Key. These are secrets and must never be exposed to clients or committed to client-side code.
• Room creation: When a user initiates a video session (e.g., schedules a meeting, starts a live stream), your server creates a room via the Video API.
• Token issuance: When a user is authorized to join a room, your server generates a JWT token and sends it to the client (via your own secure API, WebSocket, QR code, email, etc.).
• Webhook receipt: EnableX sends events (session started, participant joined, recording ready, etc.) to a webhook endpoint on your server. Your server processes these to update internal state, trigger notifications, or log analytics.
• Post-session data retrieval: After a session ends, your server retrieves CDR, recordings, transcripts, and metadata from the Video API for storage, analysis, or delivery to end users.
• User authorization: You decide who can create rooms, who can join which rooms, and what roles they have (moderator vs. participant).

Security model: Your app server is trusted. All Video API calls from your server are authenticated via HTTP Basic Auth (App ID + App Key). This is why App Key must be protected at all costs.

Tier 2: EnableX Video API

The EnableX Video API at https://api.enablex.io/video/v2 is the control plane. It is a REST API that handles provisioning and reporting.

Responsibilities:

• Room CRUD: Create, read, list, update, delete rooms. Each room gets a unique room_id.
• Token issuance: Sign and issue JWT tokens for specific users, rooms, and roles. Tokens are cryptographically signed with your App Key.
• Session lifecycle: Track session start, participant join/leave, session end. Emit webhooks for these events.
• CDR retrieval: Expose post-session CDR (participant list, durations, quality metrics) via REST API.
• Recording and artifact retrieval: Provide URLs to download recordings, transcripts, and other session artifacts.
• Configuration: Allow your server to configure room-level settings (duration, recording, streaming, etc.).

Authentication: All calls to the Video API use HTTP Basic Auth: base64-encode AppID:AppKey and pass it in the Authorization header. For example:

Authorization: Basic YXBwX2lkOmFwcF9rZXk=

Transport: All API traffic is over HTTPS. Never make Video API calls over HTTP.

Tier 3: EnableX Media Infrastructure

The EnableX media servers handle the actual WebRTC streams. This tier is managed entirely by EnableX—you do not provision or configure it.

Responsibilities:

• WebRTC signalling: Accept ICE candidates, SDP offers/answers, and codec negotiation.
• STUN/TURN: Provide STUN servers for NAT/firewall traversal. Provide TURN relays for restrictive networks. All automatically configured—you do not specify TURN servers.
• Media routing: Forward media between participants using SFU (Selective Forwarding Unit) for group mode or MCU (Multipoint Control Unit) for lecture mode. P2P mode bypasses the media server for direct peer connection.
• Codec negotiation: Support VP8, H.264 for video; Opus for audio. Automatically select best codec based on client capabilities and network conditions.
• Recording: Capture and encode session media into MP4 or WebM. Apply recording layouts (grid, spotlight, sidebar).
• Global distribution: Media servers are deployed globally. A client automatically connects to the nearest server based on geographic location and network routing. No configuration required.
• Encryption: All media is encrypted in transit via DTLS-SRTP. Signalling is encrypted via WSS (WebSocket Secure).

Client authentication: Clients do not interact with the Video API directly. Instead, clients use the EnableX SDK (Web, iOS, Android, React Native, etc.). The SDK:

1. Receives a token from your app server.
2. Validates the token client-side (optional, for early error detection).
3. Connects to the nearest EnableX media server using WebRTC.
4. Exchanges SDP and ICE candidates.
5. Establishes DTLS-SRTP encrypted media streams.
6. Sends and receives media.

The SDK abstracts all WebRTC complexity. Your client code simply calls SDK methods like joinRoom(token) and publishStream(mediaStream). The SDK handles signalling, codec negotiation, and media transport.

Room Modes: Group, Lecture, P2P

Each room operates in one of three modes, which determines media flow and participant limits.

Group Mode (SFU)

Media routing: Selective Forwarding Unit (SFU). Each participant publishes one stream; the SFU receives it and forwards it to all other participants.

Max participants: Up to 100.

Roles: All participants are equal. No moderator/participant distinction (or both are equivalent).

Typical use cases: Team meetings, collaborative sessions, peer-to-peer support, breakout rooms.

Lecture Mode (MCU)

Media routing: Multipoint Control Unit (MCU). The MCU composites and encodes streams into a single output. Moderators publish; participants receive the composited stream. Optional floor access allows participants to request to speak.

Max participants: Up to 2000 (view-only participants, thousands of listeners; actual publishers is limited by moderator control and bandwidth).

Roles: Moderator (can publish, has floor control, can mute others) and Participant (receives moderator streams, optionally can request floor access).

Typical use cases: Webinars, live streams, large classrooms, broadcast events, town halls.

P2P Mode

Media routing: Direct peer-to-peer. No server in the media path (though EnableX signalling servers still handle ICE/SDP). Media flows directly between two clients.

Max participants: 2.

Roles: Symmetric. Both participants have equal capabilities.

Typical use cases: 1-on-1 customer support, pair interviews, private consultations, low-latency calls.

What Your Server Manages

What EnableX Manages

Authentication: HTTP Basic Auth

All API calls from your app server to the Video API use HTTP Basic Auth.

Format

The Authorization header contains the word "Basic" followed by a space and a Base64-encoded string of AppID:AppKey.

# Step 1: Create the credentials string
credentials="AppID:AppKey"

# Step 2: Base64-encode it
echo -n "$credentials" | base64
# Output: QXBwSUQ6QXBwS2V5

# Step 3: Use in Authorization header
curl -X GET https://api.enablex.io/video/v2/rooms   -H "Authorization: Basic QXBwSUQ6QXBwS2V5"

Critical Security Rules

Never expose your App Key:

• Do not hardcode it in client-side code (JavaScript, mobile apps).
• Do not commit it to version control.
• Do not share it in Slack, email, or logs.
• Do not pass it as a URL parameter.
• Store it in a secure secrets manager (AWS Secrets Manager, HashiCorp Vault, environment variables in a locked CI/CD system).

Always use HTTPS: Video API calls must be over HTTPS, never HTTP. If you use HTTP, the Base64-encoded credentials are trivially decoded by a network observer.

Use separate credentials per environment: Request separate App ID + App Key pairs for development, staging, and production. If one is compromised, rotate it without affecting other environments.

Rotate regularly: Ask EnableX support to rotate your credentials every 6–12 months as a precaution.

Client Authentication (Different Path)

Clients do not authenticate with the Video API. Instead:

1. Your app server generates a JWT token for the client.
2. Your app server sends the token to the client (via your own API, WebSocket, email, etc.).
3. The client includes the token when joining a room via the SDK.
4. EnableX media servers validate the token. If valid, the client is authorized to join.

Tokens are short-lived (default 24 hours) and bound to a specific room, user, and role. If a token is compromised, it can only be used to join that one room. The App Key is never exposed to the client.

Data Flow Example: A Customer Support Call

Here's a concrete example showing all three tiers in action:

1. Customer initiates support call. Your web app calls your backend API: POST /api/support-call. Your backend verifies the customer is authenticated.
2. Your server creates a room. It calls the Video API: POST https://api.enablex.io/video/v2/rooms with mode: "p2p". EnableX returns room_id: "room_12345".
3. Your server issues tokens. It calls POST https://api.enablex.io/video/v2/rooms/room_12345/tokens twice:
   • For the customer: role: "participant", user_id: "customer_456".
   • For the agent: role: "moderator", user_id: "agent_789".
4. Your server sends tokens to clients. It sends the customer's token via your web app; it notifies the agent via push notification or SMS with the agent's token.
5. Client joins via SDK. The customer's browser (or agent's app) calls the SDK: room.join(token). The SDK connects to the nearest EnableX media server.
6. Session starts. Both clients are in the room. The media server handles WebRTC, codec negotiation, and P2P media flow.
7. Session ends. One participant disconnects. The media server detects this and closes the session. It emits a webhook: POST https://yourserver.com/webhooks/session-ended.
8. Your server retrieves post-session data. It calls GET https://api.enablex.io/video/v2/rooms/room_12345/sessions/session_xyz/cdr and GET .../recording. It stores the data and makes it available to the customer (e.g., "download recording", "view transcript").