API marque blanche

Si vous exploitez un espace de travail revendeur en marque blanche, l’API marque blanche vous permet de gérer vos propres clients finaux de façon programmatique plutôt que via le tableau de bord — construisez votre propre console d’administration, automatisez l’intégration, mettez en place des parcours d’authentification personnalisés sur votre propre domaine, ou connectez les recharges de crédits à votre système de facturation.

Chaque point de terminaison de cette page nécessite API Access, une clé API créée dans votre espace de travail en marque blanche avec la portée platform:read ou platform:write, ainsi qu’un rôle propriétaire ou administrateur. Les résultats sont toujours limités à vos propres espaces clients. Une clé émise pour un client ne peut utiliser l’API REST que tant que son espace de travail dispose également d’API Access ; émettre ou révoquer une clé n’accorde pas cette fonction.

Lister les clients de la plateforme

GET /api/v1/platform/users liste vos clients, du plus récent au plus ancien. Paginez avec limit / offset (voir la pagination) et recherchez par nom ou e-mail avec q.

curl "https://your-domain.example/api/v1/platform/users?limit=20&q=jane" \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Inscrire un client de la plateforme

POST /api/v1/platform/users crée un nouveau compte client et un espace de travail en votre nom. Deux modes :

invite (par défaut) — aucun mot de passe requis. Le compte est créé sans identifiants ; associez-le à un appel de connexion ou de génération de jeton ci-dessous pour permettre au client (ou à votre propre frontend) d’y accéder réellement.
password — vous choisissez d’emblée un mot de passe initial (8 caractères ou plus) pour le client.

curl https://your-domain.example/api/v1/platform/users \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@customer.example", "mode": "invite"}'

Une adresse e-mail déjà enregistrée n’importe où sur la plateforme échoue avec 409 — le message ne révèle jamais si ce compte se trouve dans votre périmètre ou en dehors. La réponse d’inscription inclut welcome_credit avec status, requested_credits et granted_credits. Cela permet à votre interface d’intégration d’afficher si les crédits de bienvenue ponctuels ont été accordés ou nécessitent un transfert manuel ultérieur.

Configurer les crédits de bienvenue

GET /api/v1/platform/welcome-credits renvoie le montant ponctuel configuré, l’état d’activation des comptes gratuits et des attributions automatiques, le solde actuel de votre portefeuille, ainsi que le nombre estimé de nouveaux clients que vous pouvez actuellement financer. PATCH met à jour le montant pour les futurs clients ; 800 crédits est le point de départ recommandé, et 0 désactive les attributions automatiques.

curl https://your-domain.example/api/v1/platform/welcome-credits \
  -X PATCH \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"welcome_credits": 800}'

L’enregistrement est autorisé même si le montant dépasse le solde actuel de votre portefeuille. Si le portefeuille ne peut pas couvrir l’attribution complète d’un nouveau client, l’inscription réussit tout de même avec 0 crédit de bienvenue. Ce manque n’est pas rattrapé automatiquement ; utilisez l’action de transfert de solde une fois votre portefeuille approvisionné. Les clients existants ne reçoivent jamais de crédit rétroactif, et les modifications ultérieures de ce paramètre ne s’appliquent qu’aux futurs clients.

Connecter un client de la plateforme

POST /api/v1/platform/users/login authentifie un client avec son propre e-mail et son mot de passe, et renvoie un jeton d’accès en cas de succès. Utilisez cet appel pour créer un formulaire de connexion sur votre plateforme en marque blanche plutôt que de rediriger vos clients vers la page de connexion hébergée. Les échecs de connexion renvoient la même réponse générique 401 et ne révèlent pas si un compte existe.

curl https://your-domain.example/api/v1/platform/users/login \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@customer.example", "password": "correct horse battery staple"}'

C’est la seule opération de l’API marque blanche sans équivalent MCP — des identifiants ne doivent jamais transiter par un appel d’outil MCP.

Créer un jeton utilisateur

POST /api/v1/platform/users/{user_id}/token crée une clé API pour un client sans avoir besoin de son mot de passe — utile pour un tableau de bord, un parcours d’intégration, ou une automatisation approuvée agissant au nom du client.

curl https://your-domain.example/api/v1/platform/users/USER_ID/token \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "Onboarding token", "expires_in_days": 90}'

La clé en clair n’est renvoyée qu’une seule fois — stockez-la immédiatement, elle ne pourra plus être récupérée par la suite. Elle appartient au client, pas à vous : un champ scopes omis accorde un accès complet à ce client, et non les seules portées dont dispose votre propre identifiant d’opérateur.

Déconnecter un client de la plateforme

POST /api/v1/platform/users/{user_id}/logout révoque les clés API actives et les jetons OAuth du client, dans le périmètre de votre relation client. Utilisez cet appel pour forcer une déconnexion après la compromission d’un compte ou la fin de votre relation avec ce client. Répéter la requête ne pose aucun problème.

curl https://your-domain.example/api/v1/platform/users/USER_ID/logout \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Transférer un solde

POST /api/v1/platform/users/{user_id}/balance déplace des crédits entre le solde de votre espace de travail et celui d’un client :

credits positif — accorde des crédits de votre portefeuille au client (la méthode standard pour approvisionner un compte client).
credits négatif — reprend des crédits du client vers votre portefeuille.

Dans les deux sens, le portefeuille source doit couvrir le montant — un solde de portefeuille ne descend jamais sous zéro, et une reprise qui dépasse le solde du client échoue entièrement plutôt que de s’appliquer partiellement.

curl https://your-domain.example/api/v1/platform/users/USER_ID/balance \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"credits": 50, "note": "Onboarding credit"}'

Gérer les clés API

Chaque espace de travail — y compris les espaces clients créés via cette API — peut gérer ses propres clés API via /api/v1/api-keys ou Settings → API Keys dans le tableau de bord. Un identifiant appartenant à un utilisateur peut aussi générer directement une clé pour un autre espace de travail de la même marque dont cet utilisateur est actuellement propriétaire ou administrateur, en appelant /api/v1/workspaces/{workspace_id}/api-keys. Ce point de terminaison imbriqué est une fonctionnalité multi-espaces générale et ne nécessite pas d’accès en marque blanche.

curl https://your-domain.example/api/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name": "CRM integration", "scopes": ["calls:read", "leads:write"]}'

Une clé ne peut jamais créer une autre clé disposant d’un accès plus large qu’elle-même : les scopes d’une nouvelle clé doivent être un sous-ensemble des portées de l’identifiant appelant. GET /api/v1/api-keys liste les clés d’un espace de travail sans exposer leurs secrets ; DELETE /api/v1/api-keys/{id} en révoque une.

MCP

Tout ce qui précède est aussi disponible sous forme d’outils MCP, regroupés dans le groupe platform (ainsi que list_api_keys / create_api_key / revoke_api_key dans le groupe settings). Connectez-vous avec le sélecteur de groupes :

https://your-domain.example/mcp?toolsets=platform

Outil	Correspond à
`list_platform_users`	`GET /api/v1/platform/users`
`get_platform_user`	`GET /api/v1/platform/users/{user_id}`
`register_platform_user`	`POST /api/v1/platform/users`
`get_platform_welcome_credit_settings`	`GET /api/v1/platform/welcome-credits`
`update_platform_welcome_credit_settings`	`PATCH /api/v1/platform/welcome-credits`
`create_platform_user_token`	`POST /api/v1/platform/users/{user_id}/token`
`logout_platform_user`	`POST /api/v1/platform/users/{user_id}/logout`
`transfer_platform_credits`	`POST /api/v1/platform/users/{user_id}/balance`

Il n’existe pas d’outil login_platform_user — la connexion reste réservée à REST, pour la raison indiquée plus haut. Les outils MCP acceptent soit un user_id, soit un email pour identifier le client cible ; REST prend toujours user_id depuis le chemin de l’URL.

Administration en marque blanche

Facturation

API et MCP

API marque blanche

Lister les clients de la plateforme

Inscrire un client de la plateforme

Configurer les crédits de bienvenue

Connecter un client de la plateforme

Créer un jeton utilisateur

Déconnecter un client de la plateforme

Transférer un solde

Gérer les clés API

MCP

​Lister les clients de la plateforme

​Inscrire un client de la plateforme

​Configurer les crédits de bienvenue

​Connecter un client de la plateforme

​Créer un jeton utilisateur

​Déconnecter un client de la plateforme

​Transférer un solde

​Gérer les clés API

​MCP

Lister les clients de la plateforme

Inscrire un client de la plateforme

Configurer les crédits de bienvenue

Connecter un client de la plateforme

Créer un jeton utilisateur

Déconnecter un client de la plateforme

Transférer un solde

Gérer les clés API

MCP