Paramètres API destructifs : validez avant de supprimer

Les agents IA effectuent trop facilement des appels API destructifs dès qu'une requête semble correcte sur le plan syntaxique. Un corps JSON valide, un nom de compte familier et une recherche réussie ne prouvent pas que l'agent s'apprête à supprimer le bon objet. Avant toute requête externe qui supprime, révoque, déconnecte, annule ou écrase des données, vérifiez l'identité, la propriété, le périmètre et l'actualité des informations auprès du service lui-même.

J'ai vu des ingénieurs attentifs lire une requête comme « supprimer cet environnement de test », alors que l'API l'interprétait comme « supprimer tous les environnements de cette organisation ». Le code ne comportait souvent aucun bug au sens strict. Il acceptait un sélecteur trop libre, résolvait un nom dans le mauvais compte ou faisait confiance à des données récupérées plus tôt dans l'exécution. Un agent autonome commet ces erreurs ordinaires plus vite et avec davantage d'assurance.

Ce n'est pas une raison pour demander au modèle d'être plus prudent. Placez une barrière déterministe entre la requête proposée par l'agent et la requête authentifiée. Cette barrière doit rejeter l'ambiguïté par défaut et faire approuver par un humain la cible et l'effet réels.

Une requête bien formée peut tout de même désigner le mauvais objet

Une requête ne peut être envoyée en toute sécurité qu'après avoir établi quatre faits distincts : la ressource est du bon type, son identifiant immuable est celui qui était prévu, elle appartient au compte parent approuvé et l'opération touchera l'ensemble approuvé. Les équipes mélangent souvent ces faits dans une seule recherche. C'est ce raccourci qui fait dérailler les suppressions.

Imaginons un service qui expose à la fois un nom affiché et un identifiant :

{
  "id": "env_7d3a",
  "name": "staging",
  "account_id": "acct_blue",
  "state": "active"
}

Un agent qui recherche staging a trouvé un candidat, pas une autorisation de le supprimer. De nombreux comptes possèdent un environnement staging. Même dans un seul compte, les noms peuvent être réutilisés après la disparition d'un ancien objet. La seule requête d'action sûre est construite avec l'identifiant immuable renvoyé et vérifiée par rapport à l'identifiant parent attendu.

La distinction compte particulièrement lorsqu'une API prend en charge un chemin parent comme /accounts/{account_id}/environments/{environment_id}. Vérifiez les deux segments. Ne déduisez pas la propriété parce que l'identifiant est apparu dans une ancienne réponse de recherche ou parce que l'agent a placé le même nom de compte dans son plan. Le parent présent dans l'URL d'action fait partie de la frontière d'autorisation.

Le type de ressource mérite une vérification distincte. Les API utilisent souvent un point d'accès de recherche commun ou renvoient des enregistrements mélangés. Un résultat nommé staging peut être un environnement, un projet, un groupe d'accès ou un modèle enregistré. Si le service possède plusieurs points d'accès de suppression, choisissez-les seulement après avoir vérifié le type renvoyé. Ne construisez pas un point d'accès en concaténant une chaîne de type produite par le modèle.

Enfin, définissez l'effet attendu avant d'examiner les candidats. « Supprimer l'ancien déploiement » peut signifier supprimer un enregistrement de déploiement, arrêter une tâche en cours, révoquer un jeton qui lui a été attribué ou supprimer tout l'environnement. Ces effets ne doivent pas partager une opération générique delete. Rendez le verbe demandé et le type d'objet explicites dans le contrat d'action.

Les noms aident les personnes, les identifiants contrôlent la requête

Utilisez un identifiant immuable pour adresser une ressource, mais donnez à la personne qui approuve assez de contexte humain pour repérer un mauvais choix. Une carte d'approbation qui affiche seulement env_7d3a encourage une validation automatique. Une carte qui affiche seulement staging entretient l'ambiguïté. Présentez les deux à l'opérateur, avec le compte parent et les conséquences de l'opération.

Un enregistrement de cible utile ressemble à ceci :

{
  "operation": "delete_environment",
  "account": {"id": "acct_blue", "name": "Blue Team"},
  "target": {"id": "env_7d3a", "name": "staging", "type": "environment"},
  "expected_state": "active",
  "effect": "permanently removes this environment and its managed resources"
}

Le nom affiché du compte aide l'opérateur à voir que l'agent s'est aventuré dans le mauvais locataire. Le nom de la ressource l'aide à reconnaître l'objet. Les identifiants rendent la requête non ambiguë. L'effet décrit évite une erreur d'approbation fréquente : une personne pense avoir approuvé un arrêt réversible alors que le fournisseur va supprimer des données.

Ne résolvez pas un nom en prenant le premier résultat de recherche. Les points d'accès de recherche classent souvent les résultats par pertinence, renvoient des correspondances partielles ou utilisent la pagination. Si une tâche fournit un nom exact, exigez un seul candidat après filtrage par compte parent et par type attendu. Zéro candidat doit provoquer un échec. Plusieurs candidats doivent provoquer un échec. Demander à l'agent d'en choisir un ne résout rien, car il ne dispose d'aucun élément permettant de les distinguer.

La gestion de la casse doit aussi suivre une règle propre au service. Certains fournisseurs traitent les noms en respectant la casse, d'autres les normalisent. Ne normalisez pas les noms de votre côté en supposant que le fournisseur agira de la même façon. Utilisez la ressource renvoyée par le fournisseur comme référence et conservez son libellé exact dans l'enregistrement d'approbation.

Les balises, étiquettes et descriptions fournissent du contexte, pas une identité. Elles changent souvent et les utilisateurs peuvent y écrire presque n'importe quoi. Une balise comme temporary=true peut réduire une liste examinée, mais elle ne doit pas remplacer l'association à un compte ou un identifiant de ressource immuable.

Le périmètre doit être concret avant que l'agent demande une approbation

Une opération destructive a un périmètre même si son corps de requête ne contient qu'un seul identifiant. Ce périmètre comprend le compte parent, les ressources sélectionnées, les ressources enfants que le fournisseur supprime automatiquement et tout filtre qui élargit la sélection. Rendez ce périmètre concret avant de demander une approbation.

La suppression d'un seul objet a un contrat simple : un identifiant immuable, un parent attendu et un type de ressource. La suppression groupée nécessite un autre contrat. Elle doit d'abord produire un ensemble résolu, puis obtenir une approbation pour cet ensemble ou pour un résumé limité qu'un humain peut examiner. Envoyer directement un sélecteur à un point d'accès destructif laisse au service externe le soin de décider du périmètre après l'approbation.

Supposons qu'un agent propose cette requête :

{
  "account_id": "acct_blue",
  "filter": {"label": "cleanup-candidate"},
  "delete": true
}

Ce corps masque le seul fait dont l'opérateur a besoin : quelles ressources correspondent maintenant ? Développez-le au moyen d'un appel de liste en lecture seule, refusez toute pagination que vous n'avez pas entièrement examinée et normalisez le résultat en identifiants. Présentez ensuite un nombre et un court échantillon avec les noms. Si l'ensemble dépasse la limite approuvée, arrêtez-vous et demandez une nouvelle instruction.

Ne laissez jamais un filtre absent signifier « tout ». Dans les schémas de requête, distinguez une liste vide obligatoire d'un sélecteur absent. Mieux encore, interdisez aux points d'accès destructifs d'accepter des filtres dans l'interface d'action de l'agent. Faites en sorte que la passerelle n'accepte qu'une liste d'identifiants résolus pour les opérations groupées.

Une structure pratique est la suivante :

{
  "operation": "delete_resources",
  "account_id": "acct_blue",
  "resource_type": "snapshot",
  "resource_ids": ["snap_104", "snap_105"],
  "selection_observed_at": "2025-03-08T14:32:11Z"
}

Refusez un tableau resource_ids vide, sauf si le processus l'autorise explicitement. Refusez les identifiants en double. Refusez les identifiants provenant d'un autre compte. Imposez un nombre maximal adapté à l'opération approuvée par la personne. Une limite ne remplace pas l'examen, mais elle empêche une boucle mal formée de transformer un nettoyage de deux ressources en incident touchant mille ressources.

Les suppressions en cascade font aussi partie du périmètre. Si la suppression d'un projet supprime des dépôts, des clés de déploiement, des environnements ou des enregistrements de facturation, indiquez-le avant l'approbation. Si le fournisseur n'expose les détails de la cascade qu'après un appel préalable, conservez cette réponse et exigez que l'agent la présente. « Supprimer le projet » est trop vague lorsque le projet possède des objets dépendants.

Relisez le service lorsque le temps peut modifier la cible

Une lecture préalable vérifie l'intention, mais elle ne fige pas l'objet. La ressource peut changer, changer de compte ou disparaître entre la validation et la suppression. Pour les opérations sensibles, relisez la cible juste avant la mutation et utilisez le mécanisme de contrôle de concurrence du service lorsqu'il en fournit un.

HTTP propose un mécanisme standard pour ce schéma. La RFC 9110 définit les requêtes conditionnelles avec If-Match : le serveur n'exécute la méthode demandée que si la représentation actuelle correspond à une balise d'entité fournie par le client. Un GET peut renvoyer un ETag, puis un DELETE ultérieur peut transmettre exactement cette valeur.

GET /v1/accounts/acct_blue/environments/env_7d3a HTTP/1.1
Authorization: Bearer [injected credential]

HTTP/1.1 200 OK
ETag: "v42"
Content-Type: application/json

{"id":"env_7d3a","account_id":"acct_blue","name":"staging","state":"active"}

Après avoir comparé le corps avec la cible approuvée, envoyez :

DELETE /v1/accounts/acct_blue/environments/env_7d3a HTTP/1.1
If-Match: "v42"
Authorization: Bearer [injected credential]

Si le service renvoie 412 Precondition Failed, considérez cela comme une barrière ayant fonctionné. Ne demandez pas à l'agent de réessayer la suppression sans condition. Récupérez à nouveau la ressource, comparez-la aux faits approuvés et demandez une nouvelle approbation si un fait pertinent a changé. Un conflit de version indique que l'ancienne approbation ne s'applique peut-être plus.

Certains services utilisent des numéros de révision, des horodatages de mise à jour, des champs de génération ou des jetons de requête à la place des ETag HTTP. Utilisez le mécanisme documenté par le fournisseur. S'il n'en propose aucun, réduisez l'intervalle entre la lecture finale et l'écriture, rendez l'action séquentielle et acceptez que vous ne puissiez pas prouver que la cible est restée inchangée. Cette limite doit peser dans votre décision d'autoriser ou non une suppression sans supervision.

Ne confondez pas un GET réussi avec une permission de modifier. L'identifiant de lecture peut voir davantage de choses que l'identifiant d'écriture ne peut en modifier, et l'autorisation peut changer indépendamment de l'état de l'objet. C'est la réponse de mutation qui indique si le fournisseur a accepté la requête.

La validation doit se faire à la frontière des identifiants

Une validation effectuée uniquement dans le prompt de l'agent ou dans le code généré reste indicative. Le composant qui détient ou injecte l'identifiant doit imposer les contrôles, car c'est le dernier endroit capable d'empêcher une requête sortante.

Cette frontière doit recevoir une proposition d'action structurée, pas une URL libre et des en-têtes arbitraires. Une définition d'action étroite peut exiger des champs comme l'identifiant du compte, l'identifiant de la ressource, la méthode, le type attendu et la version attendue. Elle peut construire le chemin sortant à partir de segments validés et refuser les paramètres de requête qui élargissent le périmètre.

N'acceptez pas une URL complète fournie par l'agent en essayant ensuite d'en extraire les éléments sûrs. L'encodage des URL, les clés de requête répétées, les noms d'hôte alternatifs et la normalisation des chemins transforment cette tâche en concours de parsing. Acceptez des champs typés, validez chacun d'eux par rapport au contrat du fournisseur et construisez vous-même l'URL. La même règle vaut pour les corps de requête. Générez une structure connue au lieu de transmettre un bloc dont vous n'avez pas inspecté les champs.

Une barrière minimale peut imposer cette séquence :

1. Confirmer que l'opération demandée figure dans une liste autorisée et que sa méthode est conçue pour être destructive.
2. Résoudre chaque cible déclarée par un appel de lecture effectué sous le même compte parent.
3. Comparer l'identifiant, le type, le parent et l'état requis renvoyés avec la proposition structurée.
4. Obtenir l'approbation de l'effet résolu, puis revérifier l'actualité des données et envoyer la mutation.
5. Enregistrer le résultat, y compris l'identifiant de requête du fournisseur lorsqu'il en renvoie un.

Gardez la liste autorisée réduite. Une porte de sortie générique appelée raw_http annule tous les contrôles de cet article, car l'agent peut réintroduire des destinations, des méthodes et des corps arbitraires. Les ingénieurs ajoutent ces portes de sortie lorsqu'un point d'accès manque, puis oublient leur existence jusqu'au jour où elles contournent les protections qu'ils pensaient avoir mises en place.

Les identifiants doivent rester hors du contexte de l'agent. L'agent a besoin du résultat d'une action autorisée, pas d'un jeton porteur qu'il pourrait copier dans une commande curl, un journal ou une intégration tierce. Sallyport suit ce modèle pour ses actions HTTP : il conserve l'identifiant dans son coffre chiffré, exécute lui-même la requête et renvoie le résultat à l'agent.

DELETE ne signifie pas que la requête est simple ou réversible

Les noms des méthodes HTTP ne décrivent pas tout l'effet métier. La RFC 9110 indique que DELETE demande à un serveur d'origine de supprimer l'association entre une ressource cible et sa fonctionnalité actuelle. La RFC ne promet pas que les données disparaîtront immédiatement, que les données associées survivront ou qu'une nouvelle tentative sera sans danger dans votre API particulière.

La documentation du fournisseur doit définir l'effet réel. Certaines API marquent un objet pour une suppression ultérieure. D'autres le placent en état de suppression différée. Certaines le détachent d'un parent. D'autres suppriment aussi ses enfants. Lisez les codes de réponse du point d'accès et les informations sur son cycle de vie avant de classer une opération comme peu risquée.

N'envoyez pas de corps avec DELETE, sauf si le fournisseur le documente explicitement. La RFC 9110 indique que le contenu reçu dans une requête DELETE n'a pas de sémantique généralement définie et peut amener certaines implémentations à rejeter la requête. Une API de suppression qui dépend de filtres dans un corps peut être valide pour ce fournisseur, mais elle mérite des tests supplémentaires au moyen du chemin client documenté. Elle ne doit pas servir de prétexte pour transmettre des sélecteurs libres depuis un agent.

Les nouvelles tentatives exigent la même prudence. Un délai d'attente réseau crée un résultat inconnu : le fournisseur peut avoir terminé la suppression après que votre client a cessé d'attendre. Réessayer immédiatement peut produire des journaux trompeurs, déclencher un second effet sur un point d'accès mal conçu ou supprimer une ressource de remplacement si la nouvelle tentative résout la cible par son nom.

Traitez un résultat inconnu selon une règle qui impose d'abord l'inspection. Interrogez l'identifiant immuable exact sous le parent exact. Si l'objet n'existe plus et que le modèle de suppression du fournisseur permet cette interprétation, enregistrez l'opération comme terminée, avec une première réponse incertaine. S'il existe encore, examinez son état et l'historique des requêtes du fournisseur lorsqu'il est disponible avant de décider de réessayer. Réutilisez une clé d'idempotence pour les opérations qui la prennent en charge, mais n'inventez pas une idempotence que le fournisseur ne propose pas.

Un 204 No Content indique seulement que le serveur a accepté et terminé l'interaction HTTP selon la définition de ce point d'accès. Il ne prouve pas que tous les nettoyages en aval sont terminés. Si l'action suivante de l'agent dépend de l'achèvement de la suppression, interrogez l'état documenté de l'opération ou de la ressource au lieu de considérer le corps de réponse vide comme une garantie.

L'approbation doit montrer les conséquences, pas le transport brut

Les humains prennent de meilleures décisions lorsqu'une approbation décrit l'effet en termes courants et contient les identifiants nécessaires à la vérification. Afficher une méthode, un chemin et un corps JSON est utile à un ingénieur API, mais cela impose trop de travail d'interprétation à la personne censée repérer une mauvaise cible.

Pour une seule ressource, l'approbation doit indiquer ce qui va changer, nommer le compte parent, afficher le nom et l'identifiant de la ressource et mentionner les effets irréversibles ou en cascade. Pour une opération groupée, affichez le nombre, un échantillon limité, la règle de sélection utilisée pour créer la liste et le fait que l'action finale utilise les identifiants figés plutôt que la règle.

Ne demandez pas une approbation générale au début d'une longue exécution d'agent pour l'utiliser ensuite lors de toutes les suppressions. L'ensemble cible change au fur et à mesure que l'agent découvre des ressources. Associez l'approbation à une session et à l'action résolue. Si le processus de l'agent change, l'approbation ne doit pas suivre silencieusement un nouveau processus qui pourrait utiliser un autre code ou d'autres instructions.

L'échec inverse est la fatigue liée aux approbations. Demander à quelqu'un de cliquer pour chaque lecture inoffensive lui apprend à cliquer sans lire, puis donne à une suppression dangereuse le même poids visuel. Laissez les lectures ne pas nécessiter d'interaction lorsque c'est approprié, exigez une autorisation de session pour un agent nouvellement lancé et réservez la confirmation par action aux identifiants ou aux actions ayant un effet destructif. Une personne qui voit moins de demandes peut examiner celles qui comptent.

L'enregistrement d'approbation doit avoir une durée de validité claire. Plus un agent attend après la validation, moins la vérification préalable est pertinente. Si l'action ne peut pas être exécutée rapidement, faites-la résoudre et demandez à nouveau une approbation. Cela peut sembler strict pendant une tâche de nettoyage. C'est moins coûteux que d'expliquer pourquoi une approbation datant d'une heure s'appliquait à une ressource qui avait depuis été recréée.

Les preuves d'audit doivent reconstituer la décision sans exposer de secrets

Une piste d'audit utile répond à plus que la question « une requête a-t-elle eu lieu ? ». Elle doit permettre de reconstituer ce que l'agent a proposé, ce que le service a indiqué avant la mutation, ce qu'une personne a approuvé, ce que la passerelle a envoyé et ce que le service a renvoyé.

Capturez les champs normalisés, pas seulement une chaîne de requête brute. Enregistrez le nom de l'action, l'identité de la session de l'agent, l'identifiant du compte parent, les identifiants des ressources, les versions attendues, l'heure de sélection, l'effet approuvé, l'heure d'approbation, la méthode et le chemin sortants, le statut de la réponse et l'identifiant de requête du fournisseur. Stockez des empreintes ou des formes expurgées des éléments de requête lorsqu'ils peuvent contenir des valeurs sensibles. Un journal d'audit qui copie des en-têtes d'autorisation vient de créer un second coffre d'identifiants.

Conservez la réponse de vérification préalable ou une empreinte protégée contre les modifications. Sans elle, un examinateur ultérieur ne peut pas déterminer si l'agent a supprimé le mauvais objet parce que la validation a échoué, parce que l'objet a changé après la validation ou parce que le service externe s'est comporté différemment de ce qui était documenté. Cette distinction détermine la manière de réparer l'incident.

La preuve d'intégrité compte lorsque la même machine exécute l'agent et la passerelle d'action. Un journal texte modifiable peut être édité par le processus à l'origine de l'incident. Sallyport construit ses journaux Sessions et Activity à partir d'un journal d'audit chiffré et chaîné par hachage, et sp audit verify peut vérifier cette chaîne hors ligne sans clé du coffre. Cela ne transforme pas une mauvaise approbation en bonne approbation, mais rend plus difficile la dissimulation d'une modification ultérieure du dossier.

Testez votre journalisation pour les requêtes refusées comme pour les requêtes réussies. Les refus, les approbations expirées, les conflits de version et les identifiants mal formés montrent si les contrôles bloquent réellement les actions. Un journal rempli de réussites vous apprend peu de choses sur la capacité de la barrière à refuser une requête dangereuse.

Concevez les actions destructives comme des contrats étroits

L'action API la plus sûre est volontairement limitée. Elle n'accepte qu'une opération connue, exige un parent et un identifiant d'objet connus, effectue une vérification préalable et décrit clairement son effet. Les interfaces générales semblent productives jusqu'à ce qu'un agent effectue une requête inattendue et que votre seule défense consiste à espérer qu'un opérateur remarquera un paramètre subtil.

Commencez par inventorier les actions capables de supprimer, révoquer, faire tourner, désactiver, écraser, publier ou déclencher des frais. Pour chacune, notez les champs de cible immuables, les champs parents, les états autorisés, le comportement en cascade, le mécanisme d'actualité, le comportement en cas de nouvelle tentative et le texte d'approbation. Si vous ne pouvez pas énoncer ces faits, ne proposez pas encore cette action à un agent autonome.

Faites ensuite passer volontairement des entrées incorrectes dans la barrière : un identifiant de ressource valide sous le mauvais compte, un nom affiché correspondant à deux résultats, un ETag périmé, une liste groupée vide, un filtre absent, une cible recréée sous le même nom et un délai d'attente après l'envoi. Ce sont ces entrées qui révèlent si la frontière valide le sens ou seulement le JSON.

Ne résolvez pas l'ambiguïté en demandant à l'agent d'écrire un plan plus long. Rendez l'ambiguïté impossible à représenter dans le contrat d'action. Un agent peut proposer une intention et recueillir des preuves. La frontière des identifiants doit décider si ces preuves désignent un effet autorisé unique, à cet instant et sous ce compte. Cette répartition vous donne un système que vous pouvez examiner lorsque la requête est courante et auquel vous pouvez faire confiance lorsqu'elle ne l'est pas.