Sign inGet Started

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ôleCe qu’il limiteCe que l’appelant reçoit à la limiteQui le définit
IdentifiantLes opérations que l’agent peut appeler403La personne qui crée la clé ou approuve la connexion
Clé d’idempotenceLes envois en double lorsqu’une requête fait l’objet d’une nouvelle tentativeLa réponse d’origine, renvoyée à l’identiqueL’appelant, à chaque requête
Liste d’autorisation des destinations SMSLes pays vers lesquels un envoi SMS API peut partir422 SMSDestinationNotEnabledUn identifiant disposant du droit d’écriture sms_management
Limite de dépenses quotidienne SMSLes dépenses SMS vers un pays sur une journée422 SMSDestinationDailySpendExceededUn identifiant disposant du droit d’écriture sms_management
Portefeuille prépayéLes dépenses en paiement à l’usage402 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 dans BIRD_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’écriture api_keys, l’écriture sms_management et 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 login demande un accès en lecture seule. --scope demande l’ensemble que vous indiquez, et --yolo demande 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_at lors de sa création : passé ce moment, la clé renvoie 401. 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 :

Exemple de code
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write

Authentification 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 :

Exemple de code
bird sms destinations update --destination NL=true

Modifier 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 :

Exemple de code
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 en rejected et 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 402 jusqu’à 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