---
title: "Contrôles des agents : clés à portée limitée, limites de dépenses et nouvelles tentatives sans risque"
description: "Comment Bird limite ce qu’un agent IA peut faire : clés API à portée limitée, envois idempotents, destinations SMS refusées par défaut, limites de dépenses quotidiennes par pays et portefeuille prépayé."
canonical: "https://bird.com/fr-fr/documentation/ai/agent-controls"
---

# 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](#choisir-lidentifiant-que-détient-lagent)                                | Les opérations que l’agent peut appeler                                       | `403`                                                                    | La personne qui crée la clé ou approuve la connexion                  |
| [Clé d’idempotence](#réessayer-un-envoi-sans-envoyer-deux-fois)                        | 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](#autoriser-chaque-pays-de-destination-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](#limiter-les-dépenses-sms-quotidiennes-par-pays)  | 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é](#plafonner-la-dépense-totale-avec-le-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](/docs/guides/verify/destinations) et [Voice](/docs/guides/voice/destinations) 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](/docs/ai/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**](https://bird.com/dashboard/profile/connected-apps). [Clés API et jetons OAuth](/explained/platform/api-key-or-oauth-token-and-how-do-i-rotate-one) 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` :

```bash
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](/docs/guides/authentication) 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](/docs/guides/idempotency) 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](/docs/guides/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**](https://bird.com/dashboard/w/sms/destinations), avec `bird sms destinations update` ou avec l’outil `sms_destinations_update` MCP :

```bash
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](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) 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 :

```bash
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](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) 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](/docs/guides/billing-and-usage#the-wallet) 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](/docs/knowledge-base/billing/payment-methods-wallet) traite des recharges, de la recharge automatique et des alertes de solde bas.

## Étapes suivantes

- [Inscription en libre-service](/docs/ai/self-serve-signup) : créez depuis un terminal le compte dans lequel travaille un agent.
- [Authentification et clés API](/docs/guides/authentication) : portées, expiration, rotation et révocation.
- [Limites de débit](/docs/guides/rate-limits) : 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](/docs/ai/agent-number-and-inbox) : les identités avec lesquelles un agent envoie et reçoit des messages.

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)
