Oui : à la création de la clé dans la console, choisissez ses portées (scopes) et, si besoin, les numéros autorisés ; une clé ne peut que réduire les droits du compte, jamais les élargir.
Astuce
Oui : à la création de la clé dans la console, choisissez ses portées (scopes) et, si besoin, les numéros autorisés ; une clé ne peut que réduire les droits du compte, jamais les élargir.
Vous confiez une clé à un prestataire, à un script de caisse ou à un connecteur IA. Vous ne voulez pas qu'elle puisse tout faire. Oui, une clé peut être restreinte : par portées (ce qu'elle a le droit d'appeler) et par numéros (depuis lesquels elle a le droit d'agir). Cela se règle à la création, dans la console. Une clé existante ne se modifie pas : créez-en une nouvelle et révoquez l'ancienne.
| Portée | Donne accès à |
|---|---|
| messages:send | POST /v1/messages, /v1/messages/reply, /v1/messages/interactive |
| messages:read | GET /v1/messages/{id}, GET /v1/messages/inbound, GET /v1/media/{id} |
| templates:read | GET /v1/templates |
| templates:write | POST et DELETE /v1/templates |
| balance:read | GET /v1/ping, /v1/balance, /v1/pricing, /v1/numbers, /v1/logs, /v1/storage, /v1/credits/packs et l'achat de crédits |
| connection:write | finaliser la connexion d'un numéro, déconnecter un numéro, débloquer un palier |
La liste que la console propose vient de GET /v1/console/keys/scopes : elle ne peut pas dériver de ce que le serveur applique.
Serveur qui n'envoie que des reçus → messages:send
Tableau de bord qui lit seulement → messages:read + balance:read
Intégration d'une seule agence → messages:send + allowed_numbers = [le numéro de l'agence]À la création, la console envoie ceci (session de console, pas une clé API) à POST /v1/console/keys :
{
"label": "Caisse agence Douala",
"scopes": ["messages:send"],
"allowed_numbers": ["100000000000001"]
}La réponse contient le secret (sk_live_…) une seule fois. Seule son empreinte est conservée : on peut vérifier la clé, jamais la relire.
POST /v1/console/keys/{id}/revoke (ou le bouton de la console). La clé cesse de fonctionner. GET /v1/console/keys liste vos clés avec leur préfixe, leurs portées et leurs numéros, jamais le secret.
Une clé peut aussi être limitée à une liste de templates, mais vous ne la réglez pas vous-même à la création : la console ne la propose pas. Elle existe pour les clés que la console émet avec les workflows n8n de la galerie (la clé n'envoie alors que les templates de la recette, avec un 403 « Template non autorisé pour cette clé » pour les autres). Une limite de templates au niveau du compte est un réglage administrateur : demandez-la au support.
Attention
Piège : balance:read n'est pas une portée inoffensive. Elle couvre aussi POST /v1/credits/checkout, qui peut débiter la carte enregistrée (use_saved_card). Pour un tableau de bord qui doit seulement lire, ne donnez pas cette clé à quelqu'un qui ne doit pas pouvoir acheter des crédits.
Attention
Piège : une clé en envoi seul (messages:send) ne peut pas appeler GET /v1/ping pour se tester : ping demande balance:read. Testez-la avec un vrai envoi vers votre propre numéro.
Attention
Piège : une clé ne peut que réduire. Les portées proposées sont les six portées par défaut, rien de plus. Une clé n'a jamais plus de droits que le compte. Pour les numéros, voir Plusieurs numéros.
Une clé restreinte limite les dégâts d'une fuite, elle ne la rend pas inoffensive : ne l'écrivez jamais dans un dépôt de code. Pour la tester sans payer, voir Tester sans payer.
Preuve — vérifié dans le code de l'API : api_keys.py, console_api.py, api_numbers.py, public_api.py, api_quota.py, api_send.py.