Documentation technique

API externe & SDK Web

Ce que la plateforme fait réellement aujourd'hui, vérifié en conditions réelles (Postgres + LiveKit Cloud) — pas seulement typé ou compilé.

Vue d'ensemble

Deux dépôts composent l'intégration : le backend NestJS (module External API) qui expose /api/v1/external/*, et le SDK Web publiable (@myreal/web-sdk) qui l'appelle depuis n'importe quelle app React.

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

Authentification

X-Api-Key: mlsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La clé est créée par notre équipe (pas de self-serve à ce stade) et scopée à votre organisation.
Elle n'est jamais stockée en clair côté serveur — seul son hash SHA-256 est persisté, la clé en clair n'est montrée qu'une fois à la création.
Chaque clé porte un scope produit explicite (ex. assistance, shopping) — un appel hors scope est refusé en 403, y compris pour une clé sans aucun scope défini.
Chaque clé est rattachée à une organisation — toute donnée créée est isolée et invisible aux autres organisations (vérifié : une clé d'une organisation ne peut pas agir sur une session d'une autre).

Référence API REST

Base : {baseUrl}/external — toutes les routes exigent X-Api-Key.

Sessions

POST	/sessions	Crée une session (hôte). Body : product, identity, roomName?
POST	/sessions/:roomName/join	Rejoint une session en spectateur. Body : identity
DELETE	/sessions/:roomName	Termine la session

Auction

POST	/sessions/:id/auction/items	Ajoute un article aux enchères
POST	/sessions/:id/auction/items/:productId/activate	Active un article
POST	/sessions/:id/auction/bids	Place une enchère — limité à 10 req/10s
POST	/sessions/:id/auction/validate	Valide l'article actif

Donation

POST	/sessions/:id/donations	Enregistre un don — limité à 10 req/10s
GET	/sessions/:id/donations	Liste les dons et le montant cumulé

Les 4 produits en détail

Assistance

Appel vidéo 1-à-1 ou 1-à-N. Session éphémère, sans persistance métier — les deux participants créent la session avec le même identifiant de room pour un appel symétrique.

Shopping

Un vendeur anime, les acheteurs regardent en lecture seule (droits de publication asymétriques, vérifiés).

L'interface vendeur dédiée reste à finaliser — l'UI actuelle est optimisée pour la perspective acheteur.

Auction

Cycle complet : ajout d'article, activation, enchères successives, validation au meilleur enchérisseur.

Ne traite pas le paiement réel — c'est un suivi d'enchère, l'encaissement reste un flux séparé.

Donation

Dons cumulés en temps réel pendant une session, avec historique et total.

Comme l'Auction, aucun encaissement réel n'est déclenché — suivi uniquement.

Webhooks

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

Chaque livraison est signée (HMAC SHA-256, header X-MyLiveShop-Signature). La configuration des endpoints se fait aujourd'hui côté interne, à la demande, pour chaque organisation pilote.

Quotas et limites de débit

— Quota LiveKit par organisation, incrémenté à chaque session créée — au-delà, 403.
— Auction et Donation exigent en plus un feature flag activé pour l'organisation.

Toutes les routes externes30 req/min par clé API

Enchères et dons10 req/10s par clé API

SDK Web (@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 (défaut) | viewer
/>

Le composant gère la connexion, l'erreur, puis la grille vidéo, les contrôles micro/caméra/partage d'écran et le chat. Un client bas niveau (MyRealClient) est aussi disponible pour une intégration sur-mesure.

Sécurité — état actuel

Fait et vérifié

Clés API hachées (SHA-256), jamais stockées en clair
Scope produit fail-closed
Isolation multi-tenant vérifiée
Rate limiting par clé API sur les routes sensibles

Pas encore fait

— Rotation de clé en douceur
— Auto-provisioning en self-serve
— Stockage du rate limiting distribué (Redis) pour le multi-instance

Parler à notre équipe technique