Technical documentation

External API & Web SDK

What the platform actually does today, verified under real conditions (Postgres + LiveKit Cloud) — not just typed or compiled.

Overview

Two repositories make up the integration: the NestJS backend (External API module) exposing /api/v1/external/*, and the publishable Web SDK (@myreal/web-sdk) that calls it from any React app.

Third-party app → @myreal/web-sdk (MyRealClient)
  → fetch('/external/sessions', { headers: { X-Api-Key } })
  → ApiKeyGuard → ProductEntitlementGuard → ApiKeyThrottlerGuard
  → ExternalApiService orchestrates Livestreams / LiveKit / Organizations / Webhooks
  → PostgreSQL + LiveKit Cloud (WebRTC rooms)

Authentication

X-Api-Key: mlsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are issued by our team (no self-serve yet) and scoped to your organization.
Never stored in plaintext server-side — only its SHA-256 hash is persisted; the raw key is shown once, at creation.
Each key carries an explicit product scope (e.g. assistance, shopping) — an out-of-scope call is rejected with 403, including for a key with no scope at all.
Each key belongs to one organization — all data created is isolated from other organizations (verified: a key from one org cannot act on another org's session).

REST API Reference

Base: {baseUrl}/external — every route requires X-Api-Key.

Sessions

POST	/sessions	Create a session (host). Body: product, identity, roomName?
POST	/sessions/:roomName/join	Join a session as a viewer. Body: identity
DELETE	/sessions/:roomName	End the session

Auction

POST	/sessions/:id/auction/items	Add an auction item
POST	/sessions/:id/auction/items/:productId/activate	Activate an item
POST	/sessions/:id/auction/bids	Place a bid — rate-limited to 10 req/10s
POST	/sessions/:id/auction/validate	Validate the active item

Donation

POST	/sessions/:id/donations	Record a donation — rate-limited to 10 req/10s
GET	/sessions/:id/donations	List donations and running total

The 4 products, in detail

Assistance

1-to-1 or 1-to-N video call. Ephemeral session, no business persistence — both participants create the session with the same room id for a symmetric call.

Shopping

One seller hosts, buyers watch read-only (asymmetric publish rights, verified).

A dedicated seller UI is still needed — the current UI is tuned for the buyer's perspective.

Auction

Full cycle: add item, activate, successive bids, validate to the highest bidder.

Does not process real payment — it's bid tracking only, settlement is a separate flow.

Donation

Donations tracked in real time during a session, with history and running total.

Like Auction, no real payment is triggered — tracking only.

Webhooks

session.createdsession.endedauction.item_addedauction.item_activatedauction.bid_placedauction.validateddonation.received

Every delivery is signed (HMAC SHA-256, X-MyLiveShop-Signature header). Endpoint setup is currently handled internally, on request, per pilot organization.

Quotas and rate limits

— Per-organization LiveKit quota, incremented on every session created — beyond it, 403.
— Auction and Donation additionally require a feature flag enabled for the organization.

All external routes30 req/min per API key

Bids and donations10 req/10s per API key

Web SDK (@myreal/web-sdk)

npm install @myreal/web-sdk @livekit/components-react livekit-client

import { MyRealSession } from "@myreal/web-sdk/react";
import "@myreal/web-sdk/react/style.css";

<MyRealSession
  apiKey="mlsk_..."
  product="assistance"   // assistance | shopping | auction | donation
  identity="Aminata"
  role="host"             // host (default) | viewer
/>

The component handles connection, errors, then the video grid, mic/camera/screen-share controls and chat. A low-level client (MyRealClient) is also available for custom integrations.

Security — current state

Done and verified

API keys hashed (SHA-256), never stored in plaintext
Fail-closed product scoping
Multi-tenant isolation verified
Per-API-key rate limiting on sensitive routes

Not yet done

— Smooth key rotation
— Self-serve auto-provisioning
— Distributed rate-limit storage (Redis) for multi-instance deployments

Talk to our technical team