Authentification et permissions
Chaque requête à l’API et chaque session MCP est authentifiée par une clé API. Cette page explique ce qu’est une clé, ce qu’elle peut faire, et les limites qui s’y appliquent.
Les clés API
Section intitulée « Les clés API »- Format :
ws_live_suivi de 40 caractères hexadécimaux. - Une clé appartient à l’espace de travail, pas à une personne. Elle se crée dans Paramètres, puis API & MCP, par un propriétaire ou un admin.
- Elle est affichée une seule fois, juste après la création. WhatSetter ne conserve qu’une empreinte, personne ne peut la relire ensuite.
- Tu peux la révoquer à tout moment avec Révoquer, puis Confirmer ?. Le dashboard confirme : Clé révoquée. Effectif en moins d’une minute. Révoquer coupe l’API REST et le serveur MCP en même temps.
Envoyer la clé
Section intitulée « Envoyer la clé »Passe la clé en Bearer token. L’en-tête X-Api-Key est accepté aussi.
curl https://app.whatsetter.com/api/v1/me \ -H "Authorization: Bearer ws_live_…"Sans clé tu reçois 401 missing_api_key. Avec une clé inconnue ou révoquée tu reçois 401 invalid_api_key.
Les scopes
Section intitulée « Les scopes »Quand tu crées une clé, tu choisis ses Permissions : Accès complet (tous les scopes, y compris l’envoi de messages) ou Personnalisé (tu choisis exactement ce que cette clé peut faire). Une clé sans le bon scope reçoit 403 insufficient_scope, et le message nomme le scope manquant.
| Scope | Ce qu’il débloque | Endpoints |
|---|---|---|
leads:read |
Lire les leads et leurs notes | GET /leads, GET /leads/{id}, GET /leads/{id}/notes |
leads:write |
Modifier le statut, les tags, le responsable, la prochaine action et l’issue du deal ; passer la main à un humain et la rendre à l’IA ; ajouter des notes | PATCH /leads/{id}, POST /leads/{id}/handoff, POST /leads/{id}/resume, POST /leads/{id}/notes |
conversations:read |
Boîte de réception et historique complet des messages | GET /conversations, GET /conversations/{leadId}/messages |
lists:read |
Lister tes listes de contacts | GET /lists |
lists:write |
Créer des listes et importer des contacts | POST /lists, POST /lists/{id}/leads |
campaigns:read |
Lister les campagnes | GET /campaigns |
campaigns:write |
Mettre en pause et relancer des campagnes | POST /campaigns/{id}/pause, POST /campaigns/{id}/resume |
messages:send |
Envoyer un message à un lead déjà contacté ; ajouter un lead opt-in à une campagne (ce qui envoie son premier message) | POST /messages, POST /campaigns/{id}/leads |
bookings:read |
Les rendez-vous pris par l’agent | GET /bookings |
groups:read |
Les groupes WhatsApp suivis : détail, membres, messages, arrivées et départs | GET /groups, GET /groups/{id}, GET /groups/{id}/members, GET /groups/{id}/messages, GET /groups/{id}/events |
webhooks:manage |
Créer, lister, tester et supprimer des souscriptions webhook | GET /webhooks, POST /webhooks, DELETE /webhooks/{id}, POST /webhooks/{id}/test |
blocklist:manage |
Lire, ajouter et retirer des numéros et indicatifs bloqués | GET /blocked-contacts, POST /blocked-contacts, DELETE /blocked-contacts/{id} |
team:read |
Lister les membres de l’espace (id, nom, rôle), pour attribuer des leads | GET /team/members |
links:read |
Lire les liens traqués et leurs statistiques de clics | GET /links, GET /links/{id} |
GET /me ne demande aucun scope : toute clé valide peut l’appeler.
Le moindre privilège
Section intitulée « Le moindre privilège »- Une clé par intégration (CRM, Zapier, un script, un assistant IA). Révoquer l’une ne casse pas les autres, et le dashboard montre quand chacune a servi pour la dernière fois.
- Un tableau de bord ou un rapport n’a besoin que de scopes de lecture. Donne
messages:sendseulement à l’intégration qui envoie vraiment des messages. - Les clés confiées à un assistant IA via le serveur MCP méritent le même soin : l’assistant ne peut faire que ce que la clé autorise.
Faire tourner une clé
Section intitulée « Faire tourner une clé »- Dans Paramètres, puis API & MCP, clique sur Créer une clé avec les mêmes scopes que l’ancienne.
- Mets la nouvelle clé dans ton intégration et vérifie-la avec
GET /me. - Clique sur Révoquer sur l’ancienne clé, puis Confirmer ?. Elle cesse de fonctionner en moins d’une minute.
Fais la rotation tout de suite si tu soupçonnes une fuite : une clé collée dans un chat, un ticket ou un dépôt public.
Une clé pour l’API et le serveur MCP
Section intitulée « Une clé pour l’API et le serveur MCP »Le serveur MCP n’a pas de comptes à lui. Chaque appel d’outil est un appel à l’API REST avec ta clé, donc les scopes, les limites de débit et les règles anti-ban ci-dessous s’appliquent exactement de la même façon. Révoque la clé et l’assistant perd l’accès lui aussi.
Les limites de débit
Section intitulée « Les limites de débit »Les requêtes sont comptées par espace, par minute, toutes clés confondues. La limite dépend de ton plan :
| Plan | Requêtes par minute |
|---|---|
| Free | 60 |
| Starter | 120 |
| Business | 300 |
| Scale | 1000 |
Chaque réponse porte trois en-têtes :
| En-tête | Sens |
|---|---|
X-RateLimit-Limit |
La limite de ton plan pour la fenêtre en cours. |
X-RateLimit-Remaining |
Les requêtes restantes dans la fenêtre. |
X-RateLimit-Reset |
Quand la fenêtre se remet à zéro, en ISO 8601. |
Au-delà de la limite tu reçois 429 rate_limited avec un en-tête Retry-After en secondes. Attends ce délai, puis réessaie.
Les envois de messages ont un quota quotidien séparé par numéro WhatsApp, indiqué dans les en-têtes X-Quota-*. Voir Erreurs, limites et idempotence.
L’isolation des espaces
Section intitulée « L’isolation des espaces »Une clé ne voit que l’espace auquel elle appartient. Si tu demandes un identifiant qui existe mais appartient à un autre espace, l’API répond 404 not_found, comme pour un identifiant inexistant. Elle ne répond jamais 403, donc un identifiant étranger ne se distingue pas d’un identifiant inconnu.