Clés API
Créez des clés API à accès complet ou réservées à l'envoi, limitez-les à un domaine ou à une boîte de réception, et gérez-les.
Une clé API est le secret que votre code envoie avec chaque requête. Créez-en une sous Clés API dans le tableau de bord, ou avec l’API elle-même. Une clé n’est affichée qu’une seule fois, à sa création : conservez-la donc dans votre gestionnaire de secrets.
curl https://api.billionsend.com/emails \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"from": "hello@example.com",
"to": "success@simulator.amazonses.com",
"subject": "Bonjour",
"text": "Bonjour."
}'
Les clés commencent par bs_. BillionSend ne stocke qu’un hachage de la clé : une clé perdue ne peut donc pas être réaffichée. Révoquez-la et créez-en une nouvelle.
Créer une clé
Dans le tableau de bord, ouvrez Clés API et choisissez Créer une clé API. Les propriétaires, les administrateurs et les développeurs peuvent le faire ; voir rôles dans l’équipe. Choisissez :
- Nom : de 1 à 80 caractères, pour distinguer les clés. Vous pouvez la renommer plus tard.
- Permission : Accès complet ou Envoi uniquement.
- Domaine : N’importe quel domaine, ou un domaine vérifié de votre équipe.
- Limiter à une boîte de réception (affiché dès que vous avez des boîtes de réception) : la seule boîte de réception à laquelle la clé est limitée.
Avec l’API :
curl -X POST "https://api.billionsend.com/api-keys" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production",
"permission": "sending_access",
"domain_id": "af8ad875-319f-4df5-a359-4f2430f3e766"
}'
La réponse est { "id": "…", "token": "bs_…" } : le jeton n’apparaît qu’ici. GET /api-keys liste les clés actives (jamais leurs jetons), et DELETE /api-keys/{id} en révoque une immédiatement ; les requêtes qui l’utilisent échouent aussitôt.
Permission
| Permission | Peut |
|---|---|
| Accès complet | Utiliser tous les points d’accès : envoi, contacts, segments, thématiques, campagnes, domaines, webhooks, templates, e-mails reçus et clés API. Une clé limitée à un domaine n’en atteint qu’une partie. |
| Envoi uniquement | Envoyer des e-mails (POST /emails, POST /emails/batch) et rien d’autre. Tout ce qui dépasse l’envoi, et toute lecture d’e-mails stockés, répond 403 restricted_api_key. |
Utilisez une clé réservée à l’envoi dans l’application qui envoie les e-mails transactionnels. Si une clé réservée à l’envoi fuite, elle ne permet pas de lire vos contacts, de modifier vos domaines ni de créer d’autres clés.
Limiter une clé à un domaine
Une clé limitée à un domaine travaille à l’intérieur de ce seul domaine et n’atteint rien de ce qui appartient à l’équipe entière. Un domaine doit être vérifié avant que vous puissiez y limiter une clé ; le sous-domaine de boîtes de réception partagé ne peut pas être utilisé.
| Élément | Ce que la clé peut faire |
|---|---|
| Envoi, e-mails, e-mails reçus, boîtes de réception, désinscriptions, campagnes | Uniquement ceux de ce domaine. Une requête pour un autre domaine répond 403 restricted_api_key. |
GET /emails/metrics |
Ne lit que les chiffres de ce domaine ; désigner un autre domaine dans domain_id répond 403 restricted_api_key. |
GET /domains et /domains/{id} (lire, modifier, supprimer, vérifier) |
Ne liste et ne touche que son propre domaine. Tout autre domaine, sous-domaine partagé compris, répond 404. |
/api-keys |
POST crée des clés limitées au même domaine. GET liste, et DELETE révoque, uniquement les clés limitées à ce domaine ; toute autre clé répond 404. |
| Contacts, segments, thématiques | Autorisé. Les contacts forment le carnet d’adresses partagé de l’équipe, mais la clé ne peut pas lever une désinscription valable pour toute l’équipe. Un segment ou une thématique qu’elle crée est lié à son propre domaine, et elle ne peut pas le délier. |
Webhooks (toutes les méthodes, secret de signature compris), listes de suppression, templates, propriétés de contact, GET /usage, GET /deliverability, vérifications et POST /domains |
403 restricted_api_key : ces éléments appartiennent à l’équipe entière. |
Utilisez-en une pour un service qui relève d’une seule marque : si elle fuite, elle n’atteint que le domaine de cette marque, et rien d’autre : ni vos webhooks, ni vos autres clés, ni vos autres domaines.
Limiter une clé à une boîte de réception
Une clé de boîte de réception donne à un agent IA l’accès à une boîte de réception et à rien d’autre. Elle exige l’accès complet, ne peut pas être aussi limitée à un domaine, ne peut lire, répondre, transférer et envoyer des brouillons que pour cette boîte de réception, et n’envoie que depuis son adresse. Elle cesse de fonctionner quand la boîte de réception expire ou est supprimée.
Limites
| Limite | Valeur |
|---|---|
| Clés actives par équipe | 25, identifiants SMTP compris. Révoquez-en une pour en créer une autre (sinon 422). |
| Clés actives par boîte de réception | 5, en plus des 25 de l’équipe. |
| Requêtes | 600 par minute et par clé, et 3 000 par équipe ; voir Bases de l’API. |
Qui peut créer quelle clé
- Dans le tableau de bord, les propriétaires, les administrateurs et les développeurs créent des clés.
- Une clé que vous créez avec l’API n’est jamais plus large que la clé qui l’a créée : une clé réservée à l’envoi ne peut créer que des clés réservées à l’envoi, une clé limitée à un domaine ne peut créer que des clés pour ce domaine (et ne voit et ne révoque que celles-là), et une clé de boîte de réception ne peut pas créer de clés.
- Une clé agit avec le rôle d’équipe que son créateur a aujourd’hui, vérifié à chaque requête. Le créateur est la personne qui l’a créée dans le tableau de bord (ou qui a connecté l’application qui l’a créée) ; une clé créée via l’API porte le créateur de la clé qui l’a créée. Le rôle ne restreint pas le travail courant : une clé à accès complet envoie et gère les contacts, les campagnes, les domaines, les webhooks et les clés quel que soit le rôle de son créateur (une clé limitée à un domaine fait exception, voir plus haut). Les actes à haut risque (effacer un destinataire, retirer une entrée de la liste de suppression, annuler une désinscription) exigent une clé dont le créateur est propriétaire ou administrateur à cet instant ; les autres clés répondent
403 forbidden. Si le créateur est rétrogradé, ses clés suivent le nouveau rôle dès la requête suivante. S’il est retiré de l’équipe ou la quitte, toutes les clés API qu’il a créées, les clés créées par ces clés et ses clés d’agent cessent de fonctionner immédiatement (401 invalid_api_key) et apparaissent comme révoquées ; une nouvelle invitation ne les rétablit pas. Voir rôles dans l’équipe.
La création, le renommage et la révocation d’une clé sont consignés dans le journal d’audit.
Autres clés
- Les identifiants SMTP sont des clés réservées à l’envoi, créées sur la page SMTP pour le relais SMTP.
- Les clés d’agent (
bs_agent_…) servent uniquement au serveur MCP. Elles sont créées sous MCP, limitées à la lecture seule, à la lecture et à la réponse, ou à la lecture et à l’envoi, et une équipe peut en avoir jusqu’à 20. Vos clés API habituelles ne fonctionnent pas sur le serveur MCP.