> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API marque blanche

> Gérez de façon programmatique les clients de votre plateforme revendeur — lister, inscrire, générer des jetons, connecter, déconnecter et transférer des crédits

Si vous exploitez un [espace de travail revendeur en marque blanche](/fr/admin/tenants-and-whitelabel), 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.

<Note>
  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.
</Note>

## 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](/fr/api-reference/introduction#pagination)) et recherchez par nom ou e-mail avec `q`.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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"}'
```

<Warning>
  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.
</Warning>

## 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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 :

```text theme={null}
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.