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

Source: https://docs.whatsetter.com/fr/developers/authentication/

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

- 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](/fr/developers/mcp/) en même temps.

## Envoyer la clé

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

```bash
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

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.

> **Six scopes sont nouveaux**
`prompts:read`, `prompts:write`, `knowledge:read` et `knowledge:write` sont arrivés avec les endpoints des prompts et des bases de connaissances. Une clé créée avant ne les porte pas, même une clé **Accès complet** : crée une nouvelle clé si tu as besoin de ces endpoints. C'est pareil pour `blocklist:manage`, `team:read` et `links:read`, arrivés plus tôt. Voir les guides [prompts des agents](/fr/developers/guides/prompts/) et [bases de connaissances](/fr/developers/guides/knowledge/).

> **Instagram demande une clé récente**
`instagram:read` et `instagram:write` sont arrivés avec les endpoints Instagram. Une clé **Accès complet** est la liste des scopes qui existaient le jour de sa création : une clé créée avant la sortie de ces endpoints ne les porte pas, et les routes Instagram lui répondent `403 insufficient_scope`. Crée une nouvelle clé. Les messages privés Instagram et Messenger ne demandent aucun scope Instagram : ils se lisent avec `conversations:read` et se répondent avec `messages:send`, comme WhatsApp. Voir le [guide Instagram](/fr/developers/guides/instagram/).

## 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: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](/fr/developers/mcp/) méritent le même soin : l'assistant ne peut faire que ce que la clé autorise.

## Faire tourner une clé

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.

## Une clé pour l'API et le serveur MCP

Le [serveur MCP](/fr/developers/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

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](/fr/developers/errors/).

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

## Voir aussi

- [Démarrage rapide](/fr/developers/quickstart/)
- [Erreurs, limites et idempotence](/fr/developers/errors/)
- [Serveur MCP](/fr/developers/mcp/)
- [Équipe et rôles dans le dashboard](/fr/dashboard/team/)
