Gestion des tenants

Les endpoints d’administration vivent sous /api/v1 et sont protégés par l’en-tête X-Admin-Key (opérateur de plateforme). Ils gèrent tout le cycle de vie d’un tenant après l’approvisionnement.

Libre-service vs admin de plateforme

Cette page décrit la surface X-Admin-Key (opérateur de plateforme). Un tenant peut gérer ses propres clés sans clé admin via la Console, qui expose les mêmes opérations à travers un jeton de console.

Convention de paramètres

Une seule règle à retenir :

• provision/tenant prend un corps JSON (aucun tenant_id, il est généré) ;
• toutes les autres opérations prennent ?tenant_id= en paramètre de requête, et un corps JSON uniquement quand il y a quelque chose à écrire (update/tenant).

La liste des opérations

Méthode	Chemin	Paramètre	Effet
POST	/provision/tenant	corps	Crée le tenant ; renvoie tenant_id + tenant_secret + widget_public_key (une fois)
POST	/update/tenant	?tenant_id= + corps	Mise à jour partielle (exclude_unset)
POST	/rotate/tenant-secret	?tenant_id=	Nouveau secret ; l’ancien est invalide immédiatement
POST	/rotate/widget-key	?tenant_id=	Nouvelle clé widget ; l’ancienne cesse de fonctionner immédiatement
POST	/suspend/tenant	?tenant_id=	Les appels HMAC#1 renvoient 403 jusqu’à réactivation
POST	/reactivate/tenant	?tenant_id=	Lève la suspension
GET	/fetch/tenant	?tenant_id=	Renvoie le tenant (sans secret)
GET	/fetch/tenants	?limit=&offset=	Liste paginée (sans secrets)

Mettre à jour la configuration

update/tenant n’écrit que les champs présents dans le corps. Servez-vous en pour le rate limit, l’URL de callback, le branding, les origines, les feature flags, les quotas, le plan_tier et le stripe_customer_id.

cURL

curl "$BASE_URL/api/v1/update/tenant?tenant_id=019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f" \
  -X POST \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_tier": "pro",
    "monthly_msg_quota": 50000,
    "agent_seats": 25,
    "branding_primary_color": "#0055FF"
  }'

La rotation des secrets et les changements de statut ne passent pas par update/tenant — ils ont leurs propres endpoints, ci-dessous.

Rotation du secret backend

rotate/tenant-secret génère un nouveau tenant_secret. L’ancien est invalide immédiatement : chaque backend qui signe en HMAC#1 doit basculer sur la nouvelle valeur au même instant.

curl "$BASE_URL/api/v1/rotate/tenant-secret?tenant_id=019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f" \
  -X POST \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "status_code": 200,
  "data": {
    "tenant_id": "019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "tenant_secret": "sk_...",
    "rotated_at": "2026-06-21T11:00:00Z"
  },
  "message": "Secret rotated. Save the new tenant_secret — old secret is now invalid."
}

Rotation de la clé widget

rotate/widget-key génère une nouvelle widget_public_key. C’est une opération propre au chat (l’Auth Relay n’a pas d’équivalent). L’ancienne clé cesse de fonctionner immédiatement : mettez à jour chaque balise <script data-public-key=...> et chaque configuration de SDK.

curl "$BASE_URL/api/v1/rotate/widget-key?tenant_id=019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f" \
  -X POST \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

{
  "status_code": 200,
  "data": {
    "tenant_id": "019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "widget_public_key": "pk_...",
    "rotated_at": "2026-06-21T11:05:00Z"
  },
  "message": "Widget public key rotated. Update <script data-public-key=...> on every tenant page; old key stops working immediately."
}

Secrets affichés une seule fois

Comme à l’approvisionnement, le nouveau secret et la nouvelle clé widget ne sont renvoyés que par leur appel de rotation respectif. Tout autre lecture (fetch/tenant) renvoie le tenant sans le secret. Voir aussi Cycle de vie d’un tenant.

Suspendre et réactiver

Suspendre un tenant fait répondre 403 à tous ses appels HMAC#1 jusqu’à réactivation — utile en cas d’abus ou d’impayé.

1. Suspendre — POST /suspend/tenant?tenant_id=.... Les appels backend signés sont refusés (403) ; la configuration reste intacte.
2. Réactiver — POST /reactivate/tenant?tenant_id=.... Les appels reprennent immédiatement.

# Suspendre
curl "$BASE_URL/api/v1/suspend/tenant?tenant_id=019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f" \
  -X POST -H "X-Admin-Key: YOUR_ADMIN_KEY"

# Réactiver
curl "$BASE_URL/api/v1/reactivate/tenant?tenant_id=019e4ae7-1a2b-7c3d-8e4f-5a6b7c8d9e0f" \
  -X POST -H "X-Admin-Key: YOUR_ADMIN_KEY"

Lire un ou plusieurs tenants

fetch/tenant renvoie un tenant complet sans son tenant_secret (la widget_public_key, elle, est présente). fetch/tenants pagine la liste via limit (1–500, défaut 100) et offset.

curl "$BASE_URL/api/v1/fetch/tenants?limit=50&offset=0" \
  -H "X-Admin-Key: YOUR_ADMIN_KEY"

Étapes suivantes

• Surface complète et schémas exacts. Voir la Référence API.
• Les mêmes opérations en libre-service. Voir Console.
• Comprendre le cycle de vie générique. Voir Cycle de vie d’un tenant.