Aller au contenu
Dashboard

Authentification et permissions

Clés API, les 20 scopes et ce que chacun débloque, rotation des clés, limites de débit par plan et isolation des espaces pour l'API WhatSetter.

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.

  • 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 Révoquer pour de bon. 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.

Passe la clé en Bearer token. L’en-tête X-Api-Key est accepté aussi.

Terminal window
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.

Quand tu crées une clé, tu choisis ses Permissions : Accès complet (tous les scopes, y compris l’envoi de messages et la modification des prompts) 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à en conversation, sur WhatsApp, Instagram ou Messenger ; 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}
prompts:read Lire les prompts qui font tourner un agent et leurs versions GET /campaigns/{id}/prompts, GET /campaigns/{id}/prompts/{type}, GET /campaigns/{id}/prompts/{type}/versions, GET /campaigns/{id}/prompts/{type}/versions/{versionId}
prompts:write Modifier un prompt ou restaurer une version. Le changement est en ligne tout de suite PUT /campaigns/{id}/prompts/{type}, POST /campaigns/{id}/prompts/{type}/versions/{versionId}/restore
knowledge:read Lire les bases de connaissances et leurs réponses, et y chercher comme le fait l’agent GET /knowledge-bases, GET /knowledge-bases/{id}, GET /knowledge-bases/{id}/search, GET /knowledge-bases/{id}/answers
knowledge:write Ajouter, corriger et retirer des réponses POST /knowledge-bases/{id}/answers, PATCH /knowledge-bases/{id}/answers/{answerId}, DELETE /knowledge-bases/{id}/answers/{answerId}
instagram:read Lire les comptes Instagram, les publications programmées, les chiffres et les meilleurs moments des publications, les automatisations et leurs chiffres GET /instagram/accounts, GET /instagram/posts, GET /instagram/posts/{id}, GET /instagram/insights/posts, GET /instagram/insights/best-times, GET /instagram/automations, GET /instagram/stats
instagram:write Programmer, modifier et annuler des publications (elles sont publiées publiquement) ; créer, modifier, allumer et supprimer des automatisations (une automatisation allumée écrit à de vraies personnes) POST /instagram/posts, PATCH /instagram/posts/{id}, DELETE /instagram/posts/{id}, POST /instagram/automations, PATCH /instagram/automations/{id}, DELETE /instagram/automations/{id}

GET /me ne demande aucun scope : toute clé valide peut l’appeler.

  • 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:send seulement à l’intégration qui envoie vraiment des messages.
  • Donne prompts:write seulement à une intégration ou à un assistant qui doit changer ce que disent tes agents. Avec prompts:read seul, il peut expliquer une réponse sans pouvoir rien modifier.
  • 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.
  1. Dans Paramètres, puis API & MCP, clique sur Créer une clé avec les mêmes scopes que l’ancienne.
  2. Mets la nouvelle clé dans ton intégration et vérifie-la avec GET /me.
  3. Clique sur Révoquer sur l’ancienne clé, puis Révoquer pour de bon. 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.

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 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
Social 30. Listes, groupes, liens et webhooks demandent un forfait WhatsApp : 403 not_in_plan
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.

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.