Comment sécuriser les API fonctionnelles contre les agents IA

Donnez à un agent d'IA un accès en écriture à votre projet d'API et il peut causer de réels dommages. Pas intentionnellement : les agents exécutent ce que l'invite suggère. Demandez-lui de « nettoyer les points de terminaison utilisateur » et il peut supprimer une route encore utilisée. Demandez-lui de « mettre à jour le schéma » et il peut écraser un modèle référencé par d'autres points de terminaison. L'agent ne sait pas ce qui est déployé en production ; il ne voit que les ressources qu'il est autorisé à modifier.

Essayez Apidog dès aujourd'hui

C'est une nouvelle catégorie de risques. Un humain hésite généralement avant de supprimer un point de terminaison. Un agent qui exécute une boucle dans votre terminal ne le fait pas : il lance la commande, reçoit une réponse de succès, puis passe à l'étape suivante. Si cette commande cible votre branche principale, la modification est déjà dans votre source de conception.

La solution n'est pas de bloquer les agents, mais de leur fournir un bac à sable dont ils ne peuvent pas sortir. L'AI Branch d'Apidog isole chaque modification pilotée par un agent dans une branche dédiée. Votre branche source reste intacte et rien n'atteint main tant qu'un humain n'a pas vérifié le diff et fusionné les changements.

Pour la logique de conception derrière cette fonctionnalité, consultez l'article sur AI Branch et les changements plus sûrs pilotés par des agents. Ce guide se concentre sur l'implémentation avec la CLI.

Pourquoi l'accès en écriture d'un agent est dangereux par défaut

La plupart des outils donnent à un agent un seul niveau d'accès : le projet entier. S'il peut créer un point de terminaison, il peut aussi en supprimer un. S'il peut mettre à jour un schéma, il peut aussi le remplacer par une version incompatible.

Il n'y a donc pas de séparation entre :

• « l'agent a proposé un changement » ;
• « le changement est dans la source de vérité ».

Trois modes de défaillance reviennent régulièrement :

• Écrasement : l'agent régénère un schéma à partir d'une compréhension partielle de votre API et supprime des champs nécessaires à d'autres points de terminaison.
• Suppression : l'agent « consolide » des points de terminaison et retire des routes toujours appelées par des clients actifs.
• Dérive silencieuse : l'agent effectue des dizaines de petites modifications pendant une session. Chaque changement paraît acceptable isolément, mais leur somme s'écarte de l'API déployée.

Ces scénarios ne sont pas exceptionnels. Ce sont les conséquences normales d'un agent qui travaille sur la mauvaise branche. L'objectif est donc de rendre cette branche inaccessible.

La solution : une branche d'IA isolée

Une branche d'IA est un type de branche de sprint conçu pour les opérations externes d'IA et de CLI. L'agent y effectue ses modifications, qui restent isolées jusqu'à ce que vous décidiez de les fusionner.

Installez et authentifiez d'abord l'Apidog CLI :

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Créez ensuite une branche d'IA. Utilisez un nom incluant la date, la branche source et l'objectif de la tâche :

apidog branch create --type ai \
  --name "ai/20260708-from-main-user-register" \
  --from main \
  --project <PROJECT_ID>

Points importants :

1. La branche est créée depuis main, mais cette commande ne modifie pas main.
2. La branche d'IA démarre vide.
3. Elle ne contient que les ressources importées explicitement.

Cette dernière propriété limite le rayon d'action de l'agent : il ne peut modifier que les ressources que vous lui avez fournies, pas l'ensemble du projet.

Pour afficher toutes les options d'une commande de branche :

apidog branch create -h

Importez les ressources source avant de les modifier

Une branche d'IA étant vide, commencez par importer les ressources exactes que l'agent doit modifier : points de terminaison, schémas ou documents.

Utilisez les ID des ressources concernées. Les ID sont fournis sous forme de listes séparées par des virgules :

apidog branch pick-to \
  --type ai \
  --from main \
  --to "ai/20260708-from-main-user-register" \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --project <PROJECT_ID>

La branche d'IA contient maintenant une copie des points de terminaison 1 et 2, ainsi que du schéma 3, dans leur état actuel sur main.

L'agent travaille uniquement sur ces copies :

• supprimer un point de terminaison dans la branche d'IA ne supprime pas la route active ;
• modifier un schéma n'affecte pas le schéma de main ;
• abandonner la branche annule le travail sans restauration de production.

Si vous pilotez ce flux depuis un agent de codage, les mêmes commandes s'exécutent dans sa boucle. L'Apidog CLI renvoie du JSON structuré, notamment avec agentHints.nextSteps. L'agent peut donc lire le résultat d'une commande et déterminer l'étape suivante sans interprétation manuelle.

Le guide apidog-cli dans Cursor montre ce modèle dans un éditeur.

Laissez l'agent modifier, puis vérifiez le diff

Après l'import, laissez l'agent exécuter sa tâche dans la branche d'IA. Il peut créer, mettre à jour ou supprimer des points de terminaison, schémas, documents et scénarios de test, mais toutes ses écritures restent confinées.

Avant toute fusion :

1. inspectez les changements dans la CLI ou le client Apidog ;
2. vérifiez que le diff correspond à la demande initiale ;
3. refusez ou abandonnez la branche si l'agent a modifié des ressources inattendues.

Cette revue est obligatoire. L'isolation ne protège votre branche principale que si un humain lit réellement le diff avant de l'accepter.

Déployez les changements avec une demande de fusion

La méthode de fusion dépend de la protection de la branche cible.

Si la branche cible n'est pas protégée, vous pouvez fusionner directement les ressources listées :

apidog branch merge \
  --type ai \
  --from "ai/20260708-from-main-user-register" \
  --to main \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --project <PROJECT_ID>

Cependant, main devrait être protégée. Dans ce cas, la fusion directe est bloquée et vous devez créer une demande de fusion :

apidog merge-request create \
  --from "ai/20260708-from-main-user-register" \
  --to main \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --reviewer-ids <REVIEWER_USER_IDS> \
  --description "AI branch: user register changes" \
  --project <PROJECT_ID>

Cette approche force les modifications générées par l'agent à suivre le même processus que celles d'un contributeur humain :

1. l'agent propose les changements ;
2. un relecteur examine le diff ;
3. un humain approuve ;
4. les ressources sélectionnées sont fusionnées.

La fusion ne prend en compte que les ID indiqués. Si l'agent a touché une ressource que vous ne souhaitez pas déployer, n'incluez pas son ID dans la fusion.

C'est le même modèle qu'un flux de travail API natif Git : créer une branche, proposer, réviser, fusionner. La branche d'IA applique cette discipline à un contributeur non humain.

Nettoyez les branches fusionnées et abandonnées

Archivez rapidement les branches d'IA fusionnées ou abandonnées afin de garder une liste de branches lisible.

apidog branch archive "ai/20260708-from-main-user-register" \
  --type ai \
  --project <PROJECT_ID>

Adoptez une règle simple : une branche d'IA par tâche.

Chaque branche doit correspondre à une unité de travail précise :

1. création ;
2. import des ressources nécessaires ;
3. modifications par l'agent ;
4. revue ;
5. fusion ou abandon ;
6. archivage.

Vous évitez ainsi de revoir une branche ayant accumulé plusieurs sessions de modifications sans rapport.

Hygiène de sécurité autour de la branche

La branche d'IA gère l'isolation, mais elle doit s'accompagner de quelques pratiques de base.

Utilisez des jetons à privilège minimal

Le jeton fourni à apidog login --with-token définit ce que l'agent peut faire.

Donnez à un jeton d'automatisation l'accès aux seuls projets nécessaires. N'utilisez pas un jeton de propriétaire personnel par commodité. Si un jeton est exposé ou si l'agent se comporte mal, les dommages doivent rester limités par la portée du jeton.

Protégez main

La protection de main transforme la revue avant fusion d'une recommandation en règle appliquée par la plateforme.

Avec une branche principale protégée :

• la fusion directe est bloquée ;
• les changements doivent passer par merge-request create ;
• l'agent ne peut pas écrire directement sur la branche principale.

Vérifiez chaque diff

Un agent fiable peut toujours mal interpréter une invite. Intégrez la revue dans votre workflow et ne la considérez jamais comme optionnelle.

Déléguez, puis vérifiez

Le modèle opérationnel est simple :

• déléguez une tâche ciblée à l'agent ;
• laissez-le travailler dans sa branche isolée ;
• vérifiez le résultat avant fusion.

L'agent exécute le travail ; vous conservez la décision d'acceptation.

Le même principe s'applique aux tests : l'agent exécute la suite, mais vous vérifiez les résultats du faisceau de test et le code de sortie avant de vous y fier.

Si votre spécification API est aussi versionnée dans Git, un contrôle de version OpenAPI ajoute une seconde couche d'historique pour comparer les changements suspects.

Le flux de bout en bout

Voici la séquence complète à exécuter vous-même ou à donner à un agent :

1. Créez une branche avec apidog branch create --type ai depuis main.
2. Importez uniquement les ressources nécessaires avec apidog branch pick-to.
3. Laissez l'agent modifier les copies dans la branche d'IA.
4. Vérifiez le diff dans la CLI ou le client Apidog.
5. Créez une demande de fusion avec apidog merge-request create vers un main protégé.
6. Archivez la branche avec apidog branch archive après fusion ou abandon.

À aucun moment, l'agent ne dispose d'un chemin direct pour écraser ou supprimer un point de terminaison actif sur main. Au pire, il produit une mauvaise modification dans une copie de travail que vous refusez de fusionner.

Donnez aux agents de l'espace, pas les clés

Les agents sont utiles parce qu'ils agissent vite et sans demander confirmation à chaque étape. C'est aussi pourquoi un accès en écriture sans restriction est dangereux.

Une branche d'IA isolée, un main protégé, des jetons à privilège minimal et une revue obligatoire transforment « l'agent a détruit notre API » en un simple diff que vous pouvez rejeter.

Apidog fournit ce workflow sans devoir assembler plusieurs outils. Utilisez l'Apidog CLI, créez une branche d'IA et laissez vos agents modifier une copie plutôt que votre source de vérité.

Téléchargez Apidog pour tester ce flux, puis consultez la documentation de la branche d'IA avant de l'intégrer à un workflow de production.