Contrôles des agents : clés à portée limitée, limites de dépenses et nouvelles tentatives sans risque
Un agent qui envoie des messages via Bird détient un identifiant et dépense votre solde. Cinq contrôles limitent ce qu’il peut faire. Le premier est l’identifiant lui-même. Les quatre autres ne tiennent que tant que l’identifiant de l’agent ne permet pas de les modifier : commencez donc par l’identifiant.
| Contrôle | Ce qu’il limite | Ce que l’appelant reçoit à la limite | Qui le définit |
|---|---|---|---|
| Identifiant | Les opérations que l’agent peut appeler | 403 | La personne qui crée la clé ou approuve la connexion |
| Clé d’idempotence | Les envois en double lorsqu’une requête fait l’objet d’une nouvelle tentative | La réponse d’origine, renvoyée à l’identique | L’appelant, à chaque requête |
| Liste d’autorisation des destinations SMS | Les pays vers lesquels un envoi SMS API peut partir | 422 SMSDestinationNotEnabled | Un identifiant disposant du droit d’écriture sms_management |
| Limite de dépenses quotidienne SMS | Les dépenses SMS vers un pays sur une journée | 422 SMSDestinationDailySpendExceeded | Un identifiant disposant du droit d’écriture sms_management |
| Portefeuille prépayé | Les dépenses en paiement à l’usage | 402 pour SMS et WhatsApp. L’e-mail payant est facturé après son envoi. | Un propriétaire de l’organisation ou un administrateur de facturation |
La liste d’autorisation des destinations et la limite de dépenses quotidienne décrites sur cette page s’appliquent à SMS. Verify et Voice ont chacun leurs propres paramètres de destination, avec un état initial différent. L’e-mail et WhatsApp n’ont ni liste d’autorisation des destinations ni limite de dépenses quotidienne : ce sont donc les scopes de l’identifiant et le portefeuille qui limitent un agent sur ces canaux.
Choisir l’identifiant que détient l’agent
Un agent appelle Bird avec l’un de deux types d’identifiant. Ils se distinguent par l’étendue de leur accès.
- Une clé API (
bk_) porte les scopes que vous lui attribuez et appartient à un seul espace de travail. Elle ne peut pas émettre d’autre clé, ni accéder à la facturation, aux membres ou aux paramètres de l’organisation. Votre code l’envoie comme jeton bearer. CLI et le serveur MCP local (bird mcp) utilisent la clé définie dansBIRD_API_KEY, le cas échéant, de préférence à une connexion enregistrée. - Un jeton OAuth (
bt_) est ce que détiennent CLI et le serveur MCP après la connexion d’une personne. Il porte les autorisations que cette personne a approuvées, jamais plus que celles qu’elle détient. Celles-ci peuvent inclure l’écritureapi_keys, l’écrituresms_managementet la facturation de l’organisation. Un agent muni d’un tel jeton peut émettre des clés, activer des pays et relever les limites décrites sur cette page.
Ce que peut faire un jeton OAuth dépend de la façon dont il a été créé :
bird auth logindemande un accès en lecture seule.--scopedemande l’ensemble que vous indiquez, et--yolodemande toutes les autorisations que vous pouvez déléguer. Vous approuvez le résultat dans le navigateur.- Un client MCP hébergé peut demander toutes les autorisations que vous pouvez déléguer. L’écran de consentement vous permet de choisir celles à accorder. Décochez celles dont l’agent n’a pas besoin avant d’approuver.
- Self-serve signup n’affiche pas d’écran de consentement. Les identifiants qu’elle crée détiennent toutes les autorisations que le propriétaire de la nouvelle organisation peut déléguer, y compris la facturation de l’organisation.
Pour un agent qui s’exécute sans surveillance, créez une clé API limitée et confiez-la à l’agent. Réservez la connexion plus large à la personne qui configure l’espace de travail. Vous pouvez révoquer la connexion d’un outil sous Profile > Connected apps. Clés API et jetons OAuth compare les deux types d’identifiants.
Limitez chaque clé aux produits dont elle a besoin
Une clé API porte une liste de portées, chacune correspondant à un domaine de produit au niveau read ou write. Une clé qui envoie uniquement des SMS détient sms:write. Une requête hors des portées de la clé renvoie 403 : une clé divulguée ou détournée n’atteint donc que ce que vous lui avez accordé.
Trois propriétés s’appliquent à une clé, quelles que soient ses portées :
- Une clé ne peut pas émettre une autre clé. L’émission et la rotation des clés nécessitent
api_keys:write, qui n’est pas disponible pour les clés API. Une personne l’approuve dans une session du tableau de bord ou lors d’une connexion CLI ou MCP. - Une clé reste limitée à son espace de travail. Elle ne peut accéder ni à la facturation, ni aux membres de l’organisation, ni aux paramètres de l’organisation.
- Une clé peut expirer. Définissez
expires_atlors de sa création : passé ce moment, la clé renvoie401. Vous pouvez effectuer la rotation d’une clé ou la révoquer à tout moment.
Créez une clé dans le tableau de bord ou depuis un terminal. Une connexion CLI ne peut attribuer à une clé que les portées qu’elle détient elle-même ; cette commande demande donc sms:write en plus de api_keys:write :
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:writeAuthentification et clés API contient le tableau des portées et traite de l’expiration, de la rotation et de la révocation.
Réessayer un envoi sans envoyer deux fois
Un agent qui perd une réponse ne peut pas savoir si sa requête a été acceptée. Envoyez un en-tête Idempotency-Key avec une valeur unique pour chaque envoi prévu, et répétez la même requête avec la même clé lorsque le résultat est inconnu. Bird renvoie la réponse d’origine et n’accepte le message qu’une seule fois. Une réponse rejouée contient Idempotency-Replay: true.
La garantie porte sur une seule opération acceptée par clé pendant la période de conservation. Elle couvre l’acceptation par API. La remise au téléphone est signalée séparément, par le statut du message et ses événements.
Les SDK génèrent une clé pour chaque appel qui modifie des données et la réutilisent pour leurs nouvelles tentatives automatiques. Sur CLI, passez --idempotency-key. Idempotence décrit le format de la clé, la période de conservation et ce qui se passe lorsqu’une clé est réutilisée avec une requête différente.
Autoriser chaque pays de destination SMS
La liste d’autorisation des destinations SMS refuse tout par défaut. Un envoi via SMS API part vers un pays activé dans la liste, sinon il est rejeté avec 422 SMSDestinationNotEnabled avant la résolution de l’expéditeur, et aucun message n’est accepté. Un agent dirigé vers un pays inattendu est refusé. Cela s’applique aux envois depuis votre propre code, depuis bird sms send et depuis l’outil sms_send MCP.
Les codes de vérification n’utilisent pas cette liste. Verify possède sa propre liste sous Verify destinations, où tous les pays sont activés au départ. Un identifiant disposant de l’écriture verify peut donc envoyer un code par SMS vers un pays que cette liste d’autorisation bloque. Si l’agent détient verify, désactivez aussi sur cette page les pays que vous ne desservez pas.
Activez un pays sous SMS > Destinations, avec bird sms destinations update ou avec l’outil sms_destinations_update MCP :
bird sms destinations update --destination NL=trueModifier la liste d’autorisation nécessite le scope sms_management au niveau write. Un identifiant qui ne détient que sms peut envoyer vers les pays activés, mais ne peut pas en activer d’autres. Donnez sms à l’agent qui envoie, et réservez sms_management à l’identifiant qui configure l’espace de travail.
Envoyer des SMS explique l’état initial de la liste d’autorisation et comment le pays d’origine y est ajouté.
Limiter les dépenses SMS quotidiennes par pays
Chaque pays de destination peut avoir une limite de dépenses quotidienne, dans la devise de votre portefeuille. Dès que les dépenses du jour vers ce pays atteignent la limite, les nouveaux messages vers ce pays sont refusés avec 422 SMSDestinationDailySpendExceeded jusqu’à minuit UTC. Une limite de zéro bloque le pays.
Les codes de vérification envoyés par SMS comptent dans la limite. Lorsque la limite est atteinte, Verify cesse d’envoyer des codes par SMS vers ce pays et essaie le canal suivant activé pour ce pays. Lorsqu’il ne reste aucun canal, la vérification échoue avec 422 NoAvailableChannel.
Définissez une limite aux trois mêmes endroits que la liste d’autorisation. Cette commande active les Pays-Bas et les limite à 25 EUR par jour, dans un espace de travail dont le portefeuille est en EUR :
bird sms destinations update --destination "NL=true;25EUR"La limite n’est pas exacte. Une modification de limite peut mettre jusqu’à une minute pour s’appliquer à l’envoi. Les dépenses sont comptées au moment où un message est facturé : les messages déjà acceptés peuvent donc faire dépasser la limite au total du jour, à hauteur de leur coût. Prévoyez cette marge en fixant la limite. bird sms destinations list affiche la limite de chaque pays et la consommation du jour par rapport à celle-ci.
Définir une limite exige le même accès en écriture sms_management que la liste d’autorisation : un identifiant qui ne détient que sms ne peut donc pas relever sa propre limite. Envoyer des SMS présente l’ensemble des règles.
Plafonner la dépense totale avec le portefeuille prépayé
Les envois à l’usage sont prélevés sur le portefeuille prépayé de votre organisation. Ce qui se passe lorsque le solde ne couvre pas un envoi dépend du canal :
- SMS et WhatsApp sont refusés au niveau de API avec
402. Un message déjà accepté dont la facturation échoue se termine enrejectedet n’est pas facturé. - Les e-mails d’un forfait Email payant sont facturés peu après leur envoi : le solde peut donc passer brièvement sous zéro. Une fois que le portefeuille n’a plus de solde ni de crédit, les nouveaux e-mails sont refusés avec
402jusqu’à l’ajout de fonds. - Des frais appliqués à la remise que le solde ne couvre pas ne sont pas prélevés, et le message parvient tout de même à son destinataire.
Un portefeuille vide bloque toute nouvelle dépense, mais ne plafonne pas la dépense au solde exact. Alimentez-le avec une marge pour les envois facturés après leur acceptation. Si la recharge automatique est activée, le portefeuille se recharge depuis une carte enregistrée lorsque le solde passe sous votre seuil : le solde seul ne limite alors plus ce qu’un agent peut dépenser. Facturation et consommation fait référence pour ces règles.
Les opérations de facturation exigent l’autorisation de facturation de l’organisation, org:billing. Une clé API ne peut pas la détenir : aucune clé ne peut donc recharger le portefeuille, changer de forfait ni consulter la consommation. Un jeton OAuth peut la détenir si la personne qui approuve la connexion la détient elle-même et accorde des autorisations d’organisation, comme peut le faire un propriétaire d’organisation. L’identifiant issu de l’inscription en libre-service la détient dès le départ. Donnez une clé à portée limitée à un agent qui fonctionne sans surveillance : l’ajout de fonds reste ainsi entre les mains des personnes responsables du budget.
Moyens de paiement et portefeuille traite des recharges, de la recharge automatique et des alertes de solde bas.
Étapes suivantes
- Inscription en libre-service : créez depuis un terminal le compte dans lequel travaille un agent.
- Authentification et clés API : portées, expiration, rotation et révocation.
- Limites de débit : les limites de requêtes qui s’appliquent à l’ensemble des clés de votre organisation.
- Attribuer à un agent son propre numéro de téléphone et sa propre boîte de réception : les identités avec lesquelles un agent envoie et reçoit des messages.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.