Surveiller l'expiration des tokens OAuth dans n8n avant qu'ils ne cassent un workflow

Un matin, le workflow de synchronisation HubSpot qui tournait sans accroc depuis six mois échoue sur toutes ses exécutions. Le message d'erreur : invalid_grant. Rien n'a changé côté n8n — mais le refresh token du credential OAuth2, lui, a expiré ou a été révoqué silencieusement, et personne ne l'a su avant que les leads arrêtent de remonter dans le CRM. C'est l'angle mort classique de toute automatisation branchée sur un fournisseur OAuth : Google, HubSpot, Slack, Notion, Salesforce... Ce guide construit un contrôle de santé n8n qui détecte un token sur le point de casser avant qu'il ne casse réellement un workflow métier.

Access token vs refresh token : ce qui casse vraiment

La confusion la plus fréquente est de croire qu'un credential OAuth « expire » d'un bloc. En réalité, deux objets coexistent avec des durées de vie très différentes.

L'access token est de courte durée — souvent une heure — et sert directement à appeler l'API du fournisseur. n8n le renouvelle tout seul à chaque exécution grâce au refresh token, sans aucune action de votre part : c'est le fonctionnement normal, invisible, du credential OAuth2 dans n8n.

Le refresh token, lui, a une durée de vie beaucoup plus longue (des mois, voire indéfinie) mais peut cesser de fonctionner pour des raisons qui n'ont rien à voir avec le temps qui passe : l'utilisateur révoque l'accès depuis les paramètres de sécurité de son compte Google ou HubSpot, le mot de passe du compte source change, l'administrateur de l'espace de travail retire l'application, ou — cas particulier mais fréquent en développement — le projet OAuth est encore en statut « Testing » côté fournisseur. C'est ce deuxième objet qui, lorsqu'il devient invalide, produit l'erreur invalid_grant et arrête net le workflow, sans avertissement préalable.

Le piège du statut « Testing » sur Google Cloud

Sur les intégrations Google (Gmail, Sheets, Drive, Calendar…), un piège revient très régulièrement chez les équipes qui démarrent : tant que le projet OAuth dans Google Cloud Console reste en statut Testing (application non publiée, non vérifiée par Google), tous les refresh tokens qu'il émet expirent automatiquement au bout de 7 jours, quelle que soit l'activité du workflow. Un workflow qui tournait parfaitement pendant une semaine de tests s'arrête donc brutalement le huitième jour, en production, sans qu'aucune configuration n8n n'ait changé. La correction ne se fait pas dans n8n mais côté Google : publier l'application (statut « In production ») fait passer la durée de vie du refresh token à indéfinie, sous réserve des autres causes de révocation. Le détail de la configuration initiale est couvert dans notre guide configurer OAuth2 pour Google dans n8n.

Pourquoi une alerte a posteriori ne suffit pas

Le réflexe naturel est de compter sur l'Error Workflow pour être prévenu dès qu'un node échoue. C'est nécessaire, mais insuffisant pour ce cas précis : un token révoqué un vendredi soir ne déclenchera sa première alerte que lundi matin, au premier passage du Schedule Trigger concerné — et selon la fréquence du workflow, la fenêtre entre la révocation réelle et la première exécution en échec peut représenter des heures de données perdues (leads non synchronisés, emails non traités, factures non relancées). L'Error Workflow réagit à la casse ; un contrôle de santé dédié la précède.

Construire un contrôle de santé quotidien des credentials

L'idée : un workflow n8n séparé, indépendant des workflows métier, qui teste chaque matin la validité de chaque credential OAuth critique via un appel API le plus léger possible — sans toucher aux données réelles.

Schedule Trigger (quotidien, avant les workflows métier)
        │
        ▼
Liste des credentials à tester (node Set ou table Supabase)
        │
        ▼
Pour chaque credential : appel API « léger » avec le credential
        │
   ┌────┴────┐
succès     échec (401 / invalid_grant)
   │           │
   ▼           ▼
 rien      Alerte Slack + ligne de log

Choisir un appel « léger » par fournisseur

Chaque fournisseur expose une route peu coûteuse, pensée pour ce genre de vérification, qui ne consomme ni quota significatif ni donnée métier :

• Google (Gmail, Sheets, Drive…) : un appel à l'endpoint tokeninfo ou une lecture minimale comme users.getProfile sur Gmail suffit à valider le token sans lire un seul email.
• HubSpot : un GET sur /account-info/v3/details confirme l'accès sans interroger un seul contact. Le branchement initial du credential est détaillé dans notre guide de connexion HubSpot à n8n.
• Slack : la méthode auth.test de l'API Slack a été conçue exactement pour ça — vérifier qu'un token est toujours valide.
• Notion : un GET sur /v1/users/me retourne l'utilisateur associé au token sans toucher à une seule page.

Dans n8n, le node natif du service (Gmail, HubSpot, Slack…) suffit généralement pour ce test : sélectionnez l'opération la plus légère qui existe (souvent une opération de type « get profile » ou « get me »), branchée sur le credential à vérifier. Pour un fournisseur sans node dédié, un simple HTTP Request avec authentification OAuth2 générique fait l'affaire.

Router l'échec vers une alerte exploitable

Un node IF ou Switch après chaque appel distingue le succès de l'échec (code HTTP 401, ou message contenant invalid_grant / invalid_token). En cas d'échec, le message envoyé sur Slack doit permettre d'agir immédiatement, pas seulement de constater :

🔴 Credential OAuth invalide : HubSpot (compte marketing)
Détecté : {{ $now.toFormat('dd/MM/yyyy HH:mm') }}
Action : reconnecter le credential dans n8n → Credentials → HubSpot marketing
Workflows impactés : synchro-leads-hubspot, digest-hebdo-crm

La dernière ligne — la liste des workflows qui dépendent de ce credential — est ce qui transforme une alerte technique en information actionnable pour qui reçoit le message un dimanche soir. Elle se maintient à la main dans un premier temps, ou se reconstruit par requête sur la base n8n en self-hosted, comme décrit dans notre guide sur l'audit des credentials par workflow.

Journaliser pour repérer les patterns

Comme pour toute alerte, mieux vaut journaliser chaque résultat de test (credential, date, statut) dans une table plutôt que de se fier à la seule mémoire du canal Slack. Cela permet, après quelques semaines, de repérer qu'un fournisseur donné révoque plus souvent que les autres — souvent le signe d'un compte partagé dont le mot de passe change régulièrement, ou d'un scope OAuth trop large qui déclenche des révocations de sécurité côté fournisseur. La mécanique de journalisation est identique à celle décrite dans notre guide gérer les erreurs dans n8n : une ligne par échec, avec assez de contexte pour ne pas avoir à rouvrir le workflow pour comprendre ce qui s'est passé.

Ce que dit la recherche sur la révocation de tokens

La difficulté n'est pas propre à n8n : elle est documentée dans la littérature académique sur OAuth 2.0. Une étude de Park, Kim, Park et Jung, présentée au symposium WISA (Workshop on Information Security Applications) en 2015 et publiée par Springer, « A Study of OAuth 2.0 Risk Notification and Token Revocation from Resource Server », pointe une limite structurelle du protocole : les spécifications OAuth 2.0 ne définissent pas nativement de mécanisme permettant au serveur de ressource de notifier proactivement un client qu'un token a été révoqué ou présente un risque — le client (ici, n8n) ne le découvre qu'au moment où il tente de l'utiliser, et échoue. Autrement dit, l'absence de notification préventive n'est pas un défaut de configuration de votre instance : c'est une caractéristique du protocole lui-même, ce qui rend un contrôle de santé applicatif — comme celui construit ci-dessus — la seule parade réellement disponible côté intégrateur.

Les erreurs classiques

• Confondre access token et refresh token dans le diagnostic. Un access token expiré se corrige tout seul à la prochaine exécution ; un refresh token invalide, non. Perdre du temps à re-tester si le problème est le premier alors que c'est le second retarde la vraie correction.
• Laisser un projet OAuth Google en « Testing » en production. La bombe à retardement des 7 jours touche presque tous les débutants une fois, rarement deux.
• Ne tester que sur incident. Un contrôle de santé qui ne tourne pas quotidiennement équivaut à ne pas en avoir : la valeur est justement de détecter le problème avant le premier workflow métier qui en dépend.
• Alerter sans dire quoi faire. Une notification « HubSpot : erreur » sans le nom du credential ni les workflows impactés fait perdre autant de temps qu'elle en fait gagner.
• Oublier les credentials rarement utilisés. Un workflow mensuel ou trimestriel est justement celui dont le token a le plus de chances d'avoir expiré entre deux exécutions — c'est lui qu'un contrôle quotidien protège le mieux.

Étendre le contrôle : certificats SSL et escalade PagerDuty

Le même contrôle quotidien couvre deux autres échéances silencieuses.

Certificats SSL/TLS

Un renouvellement Let's Encrypt automatique peut échouer sans bruit (droits DNS révoqués, quota de l'autorité atteint, cron arrêté). Surveiller la date d'expiration réelle du certificat servi en production détecte ces échecs avant la coupure. Listez explicitement chaque nom, sous-domaines compris (api., app., webhook.) : un wildcard partage une seule échéance, mais un certificat par sous-domaine a la sienne. Un seuil de 21 à 30 jours laisse le temps d'agir, doublé d'un second seuil à 7 jours en priorité haute. Historisez les relevés dans Supabase pour voir les renouvellements.

Escalader vers l'astreinte avec PagerDuty

Pour une alerte qui doit réveiller quelqu'un, PagerDuty prend le relais de Slack. Le node PagerDuty natif agit sur les incidents existants (Incident, Note, Log Entry, User) avec une clé API de compte. Pour déclencher, acquitter ou résoudre une alerte depuis votre contrôle, utilisez plutôt l'Events API v2 (events.pagerduty.com/v2/enqueue) avec la routing_key du service. Les incidents entrants arrivent par webhook v3 sur un node Webhook : vérifiez l'en-tête x-pagerduty-signature (HMAC-SHA256 sur le corps brut) avant tout traitement.

En résumé

Un token OAuth qui casse en production n'est presque jamais une surprise évitable — c'est un événement prévisible que la plupart des équipes découvrent seulement après coup, faute de surveillance dédiée. Un workflow n8n de quelques nodes, exécuté chaque matin avant les workflows métier, suffit à transformer une panne silencieuse du vendredi soir en une alerte actionnable du lundi matin. Si vos automatisations reposent sur plusieurs intégrations OAuth sensibles (CRM, boîte mail, facturation), ce contrôle de santé mérite sa place au même rang que les sauvegardes et le monitoring d'exécutions — pas en option ajoutée après le premier incident. Le Pack Conformité & Audit (149 €) embarque déjà la logique de journalisation Supabase append-only décrite plus haut, réutilisable telle quelle pour tracer les résultats de ce contrôle de santé.