Fonction devant une connexion
Vous placez une fonction, écrite avec votre IA, devant la connexion à une API. Avant chaque appel d’un outil, elle voit la requête et la personne qui s’en sert, vérifiée par while. Elle refuse l’appel, ou le laisse partir tel quel ou modifié.
Mis à jour le 21 novembre 2026.
Vous, à votre IA : Fais que chacun ne voie que les ventes de ses agences dans notre API.
Ce que votre agent écrit
Votre agent l’écrit dans while.yaml, à la racine de votre appli :
apiVersion: while/v1
project: sales-gateway
functions:
- name: scope
connection: sales
file: scope.js
timeout_ms: 300
Quand vous en servir
Servez-vous-en quand ce qu’un appel a le droit de faire dépend de la personne qui se sert de l’outil, par exemple quand chacun ne doit voir que ses agences.
Comment ça marche
Vous placez une fonction JavaScript, écrite avec votre IA, devant la connexion à une API. Avant chaque appel d’un outil à cette API, la fonction reçoit la requête et la personne qui se sert de l’outil, vérifiée par while, puis elle refuse l’appel ou rend la requête à envoyer.
Ce qu’il faut savoir
Une version neuve ne sert qu’après sa validation par une personne qui peut configurer la connexion, jamais par une IA. En attendant, la version validée d’avant continue de servir, et revenir à une version déjà validée ne demande pas de nouvelle validation. Tant qu’aucune version n’est validée, tout appel à la connexion est refusé (503, function-not-validated).
Le délai est de 300 ms par défaut et de 2 s au plus (timeout_ms), pour onRequest comme pour onResponse. Le corps de la requête est lu en JSON, jusqu’à 1 Mio : au-delà, ou dans un autre format, body vaut null et bodySize dit sa taille. Une réponse relue par onResponse est en JSON et fait 2 Mio au plus : une autre est refusée (502, function-response), sauf une erreur de l’API, qui repart telle quelle. Une organisation a 10 fonctions au plus : au-delà, la mise en ligne est refusée. Une connexion n’a qu’une fonction dans l’organisation, déclarée par un seul projet : une connexion inconnue, ou dont un autre projet déclare déjà la fonction, fait aussi refuser la mise en ligne.
Écrivez un message de deny qui dit quoi faire : il arrive tel quel à l’outil et à son IA, avec son statut (403 par défaut, de 400 à 499) et le code “function”. Tout autre résultat qu’un send ou un deny est aussi un refus : function-error (502) pour une exception, un résultat mal formé ou une fonction en panne, function-timeout (504) pour un délai dépassé.
La fonction ne voit ni la clé de l’API, ajoutée après elle, ni les cookies, ni Authorization, ni le jeton X-While-Identity lui-même. Elle ne joint pas Internet, et sa requête part toujours vers l’hôte de la connexion. { send: request } envoie aussi à l’API les en-têtes posés par l’outil : un en-tête auquel l’API fait confiance doit donc être écrit par la fonction, qui écrase celui de l’outil. Le droit de l’outil sur la connexion reste contrôlé. Avec le seul droit de lire (rôle connection-caller), ne passent que les GET, HEAD et OPTIONS, et les POST que la fonction rend avec read: true. Un outil qui écrit à travers la fonction a besoin du droit d’écrire (rôle connection-writer). Derrière la fonction, la connexion n’applique pas ses règles et n’apprend plus des appels : c’est la fonction qui décide.
person vaut null pour une tâche planifiée, pour un visiteur venu par un lien de partage, et quand l’outil n’a pas transmis X-While-Identity. L’outil ne peut ni choisir la personne ni changer ses revendications gardées (person.claims) : elles ne sont pas dans X-While-Identity, elles sont relues chez while. Tant qu’une personne se sert de l’outil, et jusqu’à 5 minutes après sa dernière requête, l’outil peut toutefois appeler l’API avec l’identité de cette personne, pour tout ce que la fonction lui permet.
Le périmètre d’une personne, ses agences par exemple, date du moment où elle s’est connectée (signed_in_at), il y a 8 h au plus. Ce qui lui est retiré chez votre fournisseur d’identité sort de son périmètre quand elle se reconnecte.
Avec inspectResponse: true, la réponse est lue en entier avant de repartir, sans flux, et la donnée a déjà quitté l’API quand la fonction la lit. Retirer des lignes fausse la pagination et les totaux de l’API : imposez plutôt le filtre dans la requête, et gardez onResponse pour masquer un champ ou vérifier une seule fiche.
Chaque décision est notée au journal des appels de la connexion, sans le corps.
Les outils MCP de votre agent
Votre agent s’en occupe avec les outils try_connection_function, list_connections et call_connection.