Jetons API expirés : règles de récupération pour les tâches longues d'agents

Les longues tâches d'agents échouent d'une manière particulièrement absurde lorsque personne n'est responsable de l'expiration d'un jeton. L'agent reçoit une réponse 401, répète le même appel, consomme le quota de débit et transforme parfois une écriture incertaine en plusieurs écritures. Ce n'est pas un simple problème d'authentification. C'est un défaut de conception de la récupération.

Prévoyez l'expiration comme une transition d'état normale. Confiez le renouvellement à un seul composant, classez les erreurs avant d'agir, limitez les tentatives selon la nature de l'opération et laissez une trace permettant à un opérateur de savoir si le service distant a déjà accepté le travail. Un agent ne devrait jamais avoir à deviner s'il peut créer des identifiants ou s'il est sûr de renvoyer une écriture.

L'expiration est une transition d'état, pas une panne exceptionnelle

Un jeton API expiré indique que l'autorisation associée à un identifiant de courte durée a pris fin. Il ne dit pas que la tâche a échoué. Une tâche longue peut avoir réalisé dix opérations distantes avant que la requête suivante rencontre l'expiration. Le code de récupération doit préserver cette distinction.

Les équipes regroupent souvent quatre événements différents dans une seule branche appelée auth_failed. Ce raccourci produit de mauvais comportements, car chaque événement demande une réponse différente :

• L'expiration signifie que la durée de vie du jeton est arrivée à son terme et que le responsable autorisé du renouvellement peut demander un nouveau jeton d'accès.
• La révocation signifie qu'un utilisateur, un administrateur ou un fournisseur a retiré l'autorisation. Le renouvellement peut alors échouer volontairement.
• Une authentification invalide peut signaler un en-tête mal formé, un mauvais type d'identifiant, une divergence d'émetteur ou une audience incorrecte.
• Des permissions insuffisantes signifient que l'identité reste valide, mais ne peut pas effectuer cette opération.

OAuth distingue ces cas pour une raison. La RFC 6750 définit l'erreur bearer invalid_token et indique qu'un serveur de ressources utilise une réponse 401 avec un défi WWW-Authenticate lorsque le jeton est expiré, révoqué, mal formé ou autrement invalide. C'est une indication utile du protocole, mais elle n'autorise pas votre client à renouveler aveuglément. Le serveur indique seulement qu'il a rejeté cette requête.

Une tâche suit aussi deux chronologies. Sa chronologie de travail enregistre ce qu'elle a découvert, calculé, créé et confirmé. Sa chronologie d'autorisation enregistre la génération d'identifiants qui lui a permis d'agir. Lorsqu'un jeton expire, préservez la chronologie de travail et faites passer celle de l'autorisation à renewing ou blocked. Ne réinitialisez pas toute la tâche en appelant cela une récupération.

Cette distinction compte particulièrement pour les agents, qui enchaînent des appels dépendants. Un agent peut créer une demande de modification, téléverser un artefact, puis perdre l'accès avant de pouvoir joindre l'artefact. Repartir de la première instruction peut créer une deuxième demande. Un point de contrôle durable après chaque effet distant confirmé permet à l'agent de reprendre à la pièce jointe manquante au lieu de rejouer tout le plan.

Utilisez des états explicites plutôt qu'un booléen comme authenticated :

ready -> executing -> authorization_expired -> renewal_in_progress
renewal_in_progress -> executing
renewal_in_progress -> authorization_blocked
executing -> outcome_unknown
outcome_unknown -> reconciled -> executing

outcome_unknown mérite son propre état. Une connexion peut être interrompue après que le service a validé une écriture, mais avant que l'appelant reçoive la réponse. Le renouvellement du jeton ne résout pas cette incertitude. La tâche doit rechercher l'opération avec son identifiant, son jeton d'idempotence ou un mécanisme de recherche propre au fournisseur avant de tenter à nouveau l'écriture.

Un seul composant doit être responsable du renouvellement

Le client qui détient l'identifiant de renouvellement doit renouveler le jeton d'accès. L'agent doit demander une action, sans recevoir d'identifiants renouvelables. Cette règle semble stricte jusqu'à ce que deux agents rencontrent une expiration en même temps.

Si chaque processus détient une copie du jeton de renouvellement, chacun peut renouveler de son côté. Ils entrent en concurrence, produisent une suite confuse d'événements d'identification et, avec la rotation des jetons, peuvent invalider le jeton encore détenu par un autre processus. Surtout, vous transformez chaque processus capable de lire une tâche en détenteur d'une identité persistante.

Placez un courtier d'identifiants ou une passerelle d'actions entre les agents et le fournisseur. Le courtier conserve l'identifiant de renouvellement ou l'identifiant de service, obtient des jetons d'accès de courte durée, n'en associe un à la requête qu'au moment de son exécution, puis renvoie la réponse. L'agent ne reçoit ni jeton d'accès ni jeton de renouvellement.

Cette séparation attribue à chacun un rôle clair :

• L'agent choisit l'opération autorisée à effectuer et fournit ses paramètres.
• La passerelle vérifie que la session peut effectuer la requête, sélectionne la référence d'identifiant et exécute l'appel.
• Le responsable du renouvellement renouvelle une seule fois lorsque le fournisseur signale une expiration identifiée.
• Un opérateur gère une autorisation révoquée, un nouveau consentement ou un identifiant qui exige une intervention humaine.

Ne faites pas de l'agent le responsable du renouvellement simplement parce qu'il peut appeler un point de terminaison OAuth. La capacité et l'autorité sont deux choses différentes. Un agent qui peut demander un événement de calendrier ou déployer un artefact n'a pas automatiquement le droit de prolonger l'identité d'une personne ou d'un service.

La RFC 6749 décrit les jetons de renouvellement comme des identifiants délivrés au client et utilisés pour obtenir de nouveaux jetons d'accès. Prenez le mot « client » au pied de la lettre dans votre architecture. Si votre agent n'est pas le client enregistré, il ne doit pas hériter de son jeton de renouvellement sous prétexte qu'il produit la requête API.

Il existe des cas légitimes où la tâche elle-même possède le renouvellement. Une charge machine limitée, avec son propre client enregistré, son propre espace de stockage et aucune délégation humaine, peut fonctionner ainsi. Même dans ce cas, un seul coordinateur du renouvellement doit servir toutes les opérations concurrentes de cette identité. Utilisez un mutex ou un mécanisme single-flight indexé par référence d'identifiant. Le premier appel en échec renouvelle le jeton ; les autres attendent le résultat au lieu de saturer le point de terminaison.

Un registre simple de propriété évite les conceptions floues :

{
  "credential_ref": "billing-write-prod",
  "renewal_owner": "action-gateway",
  "access_token_lifetime": "provider-defined",
  "refresh_allowed": true,
  "reauthorization_owner": "on-call-operator",
  "concurrent_refresh": "single-flight"
}

Le registre contient une référence, jamais l'identifiant lui-même. Il précise aussi qui doit agir lorsque le renouvellement ne fonctionne plus. Si personne ne peut répondre à cette question avant le déploiement, la tâche y répondra mal pendant la nuit.

Une réponse 401 exige des éléments avant de déclencher un renouvellement

Ne renouvelez que si la réponse et le registre des identifiants permettent de conclure à une expiration. Traiter chaque 401 comme une expiration masque les erreurs de configuration et peut produire une longue série de renouvellements inutiles.

Commencez par le corps d'erreur, les en-têtes et les attentes liées au format des jetons documentés par le fournisseur. Certaines API renvoient des valeurs WWW-Authenticate compatibles avec OAuth. D'autres renvoient des codes d'erreur JSON. Certaines placent les échecs d'authentification derrière une passerelle qui utilise un autre code d'état. Votre classificateur doit s'appuyer sur les signaux documentés pour ce fournisseur, puis revenir à une erreur terminale sûre.

Voici un contrat de classification utilisable :

{
  "http_status": 401,
  "provider_code": "invalid_token",
  "www_authenticate": "Bearer error=\"invalid_token\"",
  "credential_ref": "reports-read",
  "token_generation": 17,
  "decision": "renew_once"
}

Une réponse ne peut obtenir renew_once que si toutes ces conditions sont réunies : la requête a utilisé un identifiant délivré ou sélectionné par votre passerelle, cet identifiant dispose d'un chemin de renouvellement, le signal du fournisseur correspond à l'expiration documentée ou à la condition invalid_token, et la tâche n'a pas déjà renouvelé la génération 17.

Utilisez un résultat différent pour chaque classe d'échec. Un en-tête mal formé relève de configuration_error, afin qu'un développeur puisse inspecter le générateur de requêtes. Une divergence d'audience relève de credential_binding_error, qui exige de corriger la demande de jeton ou la configuration de la ressource. Une autorisation révoquée relève de reauthorization_required : le système arrête les actions externes et indique précisément à l'opérateur quelle identité doit obtenir un consentement. Une réponse 403 relève de permission_denied ; la renouveler serait un réflexe sans fondement.

Les problèmes d'horloge provoquent une part surprenante des erreurs de diagnostic. Un client qui calcule l'expiration localement peut rejeter trop tôt un jeton utilisable, tandis qu'une horloge décalée peut envoyer un jeton expiré. Enregistrez l'expiration fournie par l'émetteur lors de la réception du jeton, conservez une petite marge de sécurité et utilisez une horloge système fiable. Ne laissez pas chaque agent calculer sa propre expiration à partir d'une revendication décodée.

N'inspectez pas simplement la charge d'un jeton pour décider si vous pouvez lui faire confiance. Un JSON Web Token peut contenir une revendication exp, mais le décodage de sa charge base64url ne vérifie ni sa signature, ni son émetteur, ni son audience, ni sa révocation. Utilisez cette information comme un simple indice, après validation documentée par le composant qui l'a reçu. Les jetons d'accès opaques ne fournissent aucune charge à inspecter, ce qui est une raison de plus pour que l'appelant s'appuie sur la réponse plutôt que sur l'archéologie des jetons.

Les limites de tentatives protègent le service distant et vos preuves

Après une expiration identifiée, autorisez un renouvellement coordonné et une seule nouvelle tentative contrôlée. Des tentatives supplémentaires n'améliorent pas l'autorisation ; elles masquent surtout un renouvellement défaillant et rendent la trace d'audit plus difficile à lire.

La règle de rejeu dépend de l'opération. Une lecture supporte généralement un rejeu après renouvellement. Une écriture exige de meilleures preuves, car le service distant peut l'avoir traitée avant que la réponse d'expiration, le délai d'attente ou la perte de connexion n'atteigne l'appelant.

Classez les opérations lors de la conception de l'interface d'action :

Les noms des méthodes HTTP ne suffisent pas. PUT exprime souvent une intention idempotente, mais un fournisseur peut lui associer une notification par e-mail ou une action asynchrone en aval. POST peut être sûr si le fournisseur prend en charge un champ d'idempotence. Lisez le contrat du point de terminaison et testez le comportement réel.

Pour les opérations dotées d'un jeton d'idempotence, créez celui-ci avant le premier appel réseau et conservez-le avec une empreinte canonique de la requête. À chaque nouvelle tentative, envoyez exactement le même jeton et une charge logiquement identique. Ne créez pas un nouveau jeton après un 401. Un nouveau jeton indique au fournisseur qu'il s'agit d'une nouvelle opération, ce qui annule le but recherché.

{
  "operation_id": "job-84f3/create-draft",
  "idempotency_token": "a stable random value stored before send",
  "request_fingerprint": "method, path, normalized body hash",
  "attempt": 1,
  "authorization_generation": 17
}

L'expression « normalized body hash » est importante. Si le générateur de nouvelles tentatives modifie un horodatage, l'ordre d'un tableau ou un libellé généré, il peut transformer silencieusement le même jeton d'idempotence en requête incompatible. Certains fournisseurs rejettent cette différence, d'autres la traitent de manière incohérente. Conservez le premier corps sérialisé ou canonisez-le une fois pour le réutiliser.

Les limites de débit et les nouvelles tentatives réseau doivent partager ce budget. Un agent qui utilise trois tentatives réseau, puis une tentative de renouvellement, puis trois autres tentatives réseau a créé sept occasions de dupliquer ou de surcharger une opération. Définissez un budget unique au niveau de l'opération. Une lecture sûre peut par exemple autoriser un appel initial, un chemin de renouvellement et un rejeu. Une action similaire à un paiement peut n'autoriser que l'appel initial, puis une réconciliation.

Consignez aussi chaque tentative supprimée. Les opérateurs doivent voir que le système s'est volontairement arrêté après renewal_attempted=true, et non supposer que l'agent a planté. Cette trace indique aussi qu'un fournisseur a peut-être changé le format d'une erreur et que votre classificateur refuse désormais une récupération qu'il autorisait auparavant.

Les points de contrôle permettent de reprendre une tâche sans inventer son passé

Une tâche longue d'agent doit conserver séparément les effets distants terminés et l'intention en attente, car un jeton renouvelé ne peut pas dire ce qui s'est produit avant l'échec. Le mauvais modèle consiste à ne conserver qu'une conversation ou le plan final de l'agent, puis à lui demander de reconstruire l'état après une interruption.

Utilisez un journal de tâche contenant des enregistrements qu'un programme peut réconcilier. Chaque appel externe prévu doit avoir un identifiant d'opération stable. Chaque résultat confirmé doit conserver l'identifiant de ressource du fournisseur, sa version ou son ETag si disponible, ainsi que l'empreinte de la requête. Chaque résultat incertain doit indiquer la règle de recherche permettant de le résoudre.

Un point de contrôle compact peut ressembler à ceci :

{
  "task_id": "release-2025-04-17-42",
  "completed": [
    {"operation_id": "create-change", "remote_id": "CR-819", "version": "6"},
    {"operation_id": "upload-bundle", "remote_id": "asset-552"}
  ],
  "pending": {
    "operation_id": "attach-bundle",
    "request_fingerprint": "POST /changes/CR-819/assets body-sha256:...",
    "reconcile": "list assets for CR-819 and match asset-552"
  },
  "authorization_state": "authorization_expired"
}

La tâche n'a pas besoin de sauvegarder chaque pensée intermédiaire. Elle doit conserver assez de faits pour déterminer la prochaine action distante sûre. Gardez les secrets, les en-têtes bearer et les réponses de renouvellement hors de ce journal. Ces éléments appartiennent au responsable des identifiants, pas au stockage général des tâches.

Les conditions de version comptent pendant une pause. Si la tâche a lu la version 6 d'un document avant l'expiration et reprend une heure plus tard, un autre acteur a peut-être modifié ce document. Utilisez des ETags, des numéros de révision, des en-têtes conditionnels ou des champs de concurrence propres au fournisseur lorsqu'ils existent. Si la condition échoue, indiquez à l'agent que l'ancien plan ne s'applique plus. Ne renouvelez pas le jeton pour écraser un état plus récent sous prétexte que la tâche pense posséder le monde.

C'est ici que le travail autonome doit avoir une limite de jugement. Une tâche peut reprendre sans risque un téléversement dont elle a déjà enregistré la destination et le hachage. Elle ne doit pas replanifier à la légère un déploiement, modifier une approbation ou choisir une autre cible après que son contexte initial a vieilli. Marquez ces opérations comme nécessitant une nouvelle confirmation après récupération.

La réponse de récupération doit indiquer à l'agent ce qu'il peut faire

Une passerelle d'actions doit renvoyer un résultat de récupération structuré, et non une phrase d'authentification vague qui invite l'agent à improviser. Le résultat doit indiquer si l'appel a été exécuté, si la passerelle a renouvelé l'autorisation, si le rejeu est permis et si une intervention humaine est nécessaire.

Un résultat utile sépare l'état d'exécution de l'état des identifiants :

{
  "operation_id": "attach-bundle",
  "execution_state": "not_sent",
  "authorization_state": "reauthorization_required",
  "retry_allowed": false,
  "credential_ref": "release-api",
  "operator_action": "Reauthorize the release-api connection, then resume task release-2025-04-17-42",
  "safe_resume_from": "attach-bundle"
}

not_sent signifie que la passerelle s'est arrêtée avant de transmettre la requête au client réseau. outcome_unknown signifie qu'elle ne peut pas l'affirmer. Ne réduisez pas ces deux cas à failed. Le premier peut attendre une réautorisation. Le second doit être réconcilié avec le service distant avant toute nouvelle tentative.

Les agents ont aussi besoin d'un vocabulaire limité pour la récupération. Donnez-leur des résultats comme completed, renewed_and_replayed, needs_reconciliation, reauthorization_required, permission_denied et configuration_error. Chaque résultat doit correspondre à un comportement autorisé. L'agent peut continuer après renewed_and_replayed, effectuer une réconciliation en lecture seule documentée après needs_reconciliation et arrêter les écritures externes après reauthorization_required.

Évitez de renvoyer les réponses brutes du fournisseur comme unique signal. Les détails bruts sont utiles pour le diagnostic, mais les agents peuvent mal les interpréter, surtout lorsque les fournisseurs utilisent des formulations différentes. Conservez la réponse brute dans un enregistrement de diagnostic protégé et renvoyez à l'appelant une décision stable et lisible par machine.

Un bon message d'erreur nomme la référence de l'identité et l'opération bloquée sans exposer de secret. « L'identifiant release-api doit être réautorisé avant l'exécution de attach-bundle » indique à l'opérateur où agir. « Non autorisé » ne dit rien à personne.

Les identifiants de renouvellement exigent des contrôles plus stricts que les jetons d'accès

Un identifiant de renouvellement mérite une protection renforcée, car il peut généralement rester valide plus longtemps que le jeton d'accès qu'il remplace. Ne résolvez pas l'expiration en distribuant cet identifiant à chaque espace de travail d'agent, répertoire de compilation, variable d'environnement ou transcription.

Les bonnes pratiques de sécurité OAuth 2.0, RFC 9700, recommandent la rotation des jetons de renouvellement ou des jetons de renouvellement liés à l'expéditeur pour les clients publics. La prise en charge varie selon les fournisseurs, mais la leçon de sécurité reste valable avec un autre protocole : un identifiant renouvelable volé offre une fenêtre d'utilisation abusive beaucoup plus longue qu'un jeton bearer ordinaire de courte durée.

Conservez les éléments de renouvellement dans le coffre-fort d'identifiants chiffré de la passerelle d'actions. Limitez les définitions d'actions qui peuvent les sélectionner, exigez une approbation humaine explicite lorsque l'action le justifie et faites de la réautorisation une action distincte de l'opérateur. Un coffre-fort verrouillé doit refuser le travail plutôt que permettre aux agents de récupérer des secrets copiés dans des fichiers de configuration.

Sallyport suit ce modèle pour les actions HTTP et SSH prises en charge : son coffre-fort chiffré conserve l'identifiant, tandis que l'agent demande une action par l'intermédiaire de son shim MCP et ne reçoit que le résultat. Cette séparation est utile, car l'agent ne peut pas imprimer un identifiant de renouvellement dans son propre contexte lorsque la récupération échoue.

Soyez rigoureux avec les réponses de renouvellement. Certains fournisseurs font tourner l'identifiant de renouvellement et invalident l'ancienne valeur dès son utilisation. Le responsable doit remplacer atomiquement la valeur stockée avant de libérer les appels en attente. S'il écrit le nouveau jeton d'accès mais perd le nouvel identifiant de renouvellement, la tâche peut fonctionner brièvement, puis échouer définitivement à l'expiration suivante.

Ne consignez jamais ces champs : Authorization, jeton d'accès, jeton de renouvellement, secret client, assertion signée ou corps complet du point de terminaison de jeton. Le masquage ne suffit pas lorsque les systèmes copient les objets de requête bruts avant l'exécution du masque. Concevez le journal pour recevoir des références d'identifiants et des numéros de génération plutôt que des structures contenant des secrets.

L'approbation humaine doit restaurer l'autorité, pas créer une avalanche de tentatives

L'approbation humaine n'est utile que si elle correspond à une décision claire : autoriser cette exécution d'agent, autoriser cet appel sensible ou restaurer une autorisation révoquée. Un bouton générique « réessayer » après une expiration transforme souvent l'opérateur en simple validateur d'une action mal définie.

Séparez les approbations. La réautorisation donne au responsable des identifiants une nouvelle autorisation ou un chemin de renouvellement utilisable. L'autorisation de session décide si ce processus d'agent peut demander des actions. L'approbation par appel décide si une opération sensible peut être effectuée maintenant. Ce sont des décisions différentes, et les fusionner produit soit trop de demandes, soit des permissions permanentes excessives.

Lorsqu'un identifiant doit être réautorisé, affichez la référence concernée, le libellé de l'identité ou de la connexion, l'opération bloquée et le point de contrôle de la tâche. N'affichez pas le jeton. Une fois l'autorisation restaurée, la passerelle ne doit reprendre que l'opération en attente enregistrée dans le point de contrôle. Elle ne doit pas rejouer silencieusement tous les appels échoués de la transcription de l'agent.

L'échelle de décision fixe de Sallyport convient bien à cette limite : un coffre-fort verrouillé refuse toute action, les nouveaux processus d'agents nécessitent par défaut une approbation de session et certains identifiants peuvent exiger une approbation à chaque utilisation. Ces contrôles ne tentent pas de déduire l'intention à partir d'un ensemble de règles, ce qui aide lorsqu'un identifiant expiré interrompt une exécution par ailleurs légitime.

La fatigue liée aux approbations est généralement un défaut de conception. Si un opérateur reçoit douze demandes parce que dix appels parallèles remarquent la même expiration, le coordinateur du renouvellement n'a pas regroupé l'événement. Présentez une seule demande de réautorisation, faites attendre les autres appels et communiquez la décision obtenue à chaque tâche.

N'utilisez pas l'approbation pour masquer une écriture dont le résultat est inconnu. Dans ce cas, la bonne demande consiste à demander si l'opérateur veut réconcilier l'état distant, pas s'il veut réessayer. Une personne peut autoriser un doublon par erreur aussi facilement qu'un agent.

Les tests d'expiration doivent inclure les écritures incertaines et les travailleurs concurrents

Un test de renouvellement qui renvoie un 401 synthétique avant une lecture prouve peu de choses. Les échecs qui coûtent cher apparaissent aux frontières : pendant un travail parallèle, après la validation d'une écriture, lors de la rotation d'un identifiant de renouvellement ou après la révocation d'une autorisation.

Construisez un fournisseur de test ou un dispositif HTTP contrôlable qui enregistre les identifiants d'opération reçus et injecte des échecs à des points définis. Vos assertions doivent examiner à la fois l'enregistrement de l'effet distant et celui de l'audit local. Une réponse finale réussie peut cacher une création en double.

Exécutez ces scénarios avant de faire confiance à un agent de longue durée :

1. Faites expirer le jeton d'accès avant une lecture. Vérifiez qu'un seul travailleur renouvelle le jeton et que toutes les lectures en attente utilisent la nouvelle génération.
2. Faites-le expirer avant une écriture idempotente. Vérifiez que la passerelle renouvelle une fois et rejoue avec l'identifiant d'opération et le corps d'origine.
3. Supprimez la réponse après l'enregistrement d'une écriture non idempotente par le fournisseur. Vérifiez que la tâche passe à outcome_unknown, lance sa recherche et ne crée pas un second effet.
4. Révoquez l'autorisation avant le renouvellement. Vérifiez que chaque action dépendante s'arrête avec reauthorization_required et qu'aucune boucle n'appelle continuellement le point de terminaison de jeton.
5. Renvoyez un identifiant de renouvellement qui a été remplacé, puis interrompez le stockage. Vérifiez que la passerelle détecte le remplacement incomplet et bloque le renouvellement futur au lieu d'utiliser une copie obsolète.

Testez explicitement le temps. Injectez une horloge dans le composant d'identifiants afin de placer l'expiration juste avant la construction de la requête, juste après celle de l'en-tête et pendant qu'une requête attend dans une file. Attendre l'expiration réelle d'un jeton ralentit les tests et laisse les cas de synchronisation importants non testés.

Enfin, testez le chemin d'audit sans accès au coffre-fort. Vous devez pouvoir vérifier que la suite des appels tentés et des décisions de renouvellement n'a pas changé, même si vous ne pouvez pas déchiffrer chaque enregistrement. sp audit verify de Sallyport vérifie sa chaîne de hachage sur les données d'audit chiffrées sans nécessiter de clé de coffre-fort. C'est la bonne forme de vérification lors d'un incident où l'accès aux identifiants peut rester verrouillé.

Une tâche qui gère bien l'expiration agit moins lorsque l'autorisation échoue. Elle s'arrête, classe l'échec, laisse un seul responsable renouveler l'identifiant, réconcilie l'incertitude et reprend uniquement l'opération enregistrée. Cette retenue évite les effets secondaires en double et laisse à l'opérateur des preuves plutôt qu'un amas de nouvelles tentatives.