Cycle de vie du jeton en pratique

Chaque guide de flux OAuth mentionne refresh_token, mais une intégration longue durée (qui s’exécute sur de nombreuses requêtes, workers ou jours) a besoin de plus qu’un simple remplacement du jeton à son expiration. Cette page couvre les durées de vie réelles des jetons, la mise en cache d’un jeton entre plusieurs workers, le moment où rafraîchir, et ce qui peut invalider un jeton avant qu’il n’expire normalement.

---

Durées de vie des jetons par flux

La durée de vie du jeton d’accès est une durée fixe, identique pour chaque flux. Celle du jeton de rafraîchissement ne l’est pas : elle dépend du flux OAuth qui l’a émis.

Flux	TTL du jeton d’accès	TTL du jeton de rafraîchissement
Flux Client Credentials	Environ 1 heure	Environ 30 jours
Flux pour application native (PKCE, redirection loopback)	Environ 1 heure	Pas d’expiration fixe : reste valide jusqu’à être remplacé par rotation ou révoqué
Authorization Code + Custom Redirect Flow	Environ 1 heure	Pas d’expiration fixe : reste valide jusqu’à être remplacé par rotation ou révoqué

Note

Les deux flux Authorization Code émettent un jeton de rafraîchissement sans aucune horloge de session. Il ne reste pas pour autant inutilisé indéfiniment : c’est un jeton à usage unique, remplacé à chaque rafraîchissement (voir Races de rafraîchissement concurrent ci-dessous), et il cesse de fonctionner immédiatement si la grant est révoquée.

Mettez le jeton en cache, n’en générez pas un par requête

Demander un nouveau jeton d’accès à chaque appel API, ou indépendamment dans chaque processus worker, fonctionne mais gaspille un aller-retour à chaque requête pour un jeton déjà valide pendant environ une heure. Demandez un seul jeton, mettez-le en cache (en mémoire pour un processus unique, ou dans un store partagé comme Redis pour une flotte de workers) sous la clé de l’identifiant qui l’a émis, et transmettez le jeton mis en cache à chaque requête jusqu’à ce qu’il approche de son expiration.

Cela compte aussi pour le jeton de rafraîchissement : moins il y a de processus qui l’échangent indépendamment, moins vous risquez de rencontrer la race condition décrite ci-dessous.

Rafraîchir à l’expiration, pas seulement sur 401

Comme la TTL du jeton d’accès est fixe et connue à l’avance, rafraîchissez de manière proactive : suivez le moment où vous avez obtenu le jeton (ou décodez son claim exp) et demandez-en un nouveau juste avant cette échéance, plutôt que d’attendre qu’une requête échoue d’abord.

Gérez tout de même une requête échouée en secours, mais distinguez selon l’erreur reçue :

• 401 avec not_authenticated : la requête ne portait aucun jeton porteur exploitable. C’est un bug côté client (en-tête Authorization manquant ou mal formé), pas un signal de rafraîchissement.
• 401 avec invalid_token : la vérification de signature ou d’expiration du jeton a échoué. Rafraîchissez et réessayez une fois.
• 403 : jamais un problème de jeton. Le jeton est valide ; l’appelant n’a pas le scope, l’accès au contenu ou le rôle que l’opération requiert. Rafraîchir n’y changera rien. Consultez Codes d’erreur : Limitation de débit, authentification et contrôle d’accès pour le détail complet de chaque code.

Races de rafraîchissement concurrent

Un jeton de rafraîchissement est à usage unique : l’échanger avec grant_type=refresh_token invalide ce jeton et émet ensemble un nouveau jeton d’accès et un nouveau jeton de rafraîchissement. Si plusieurs workers partagent un même jeton de rafraîchissement mis en cache et que deux d’entre eux tentent de rafraîchir presque au même moment, un seul échange réussit ; l’autre reçoit un 401 générique, pas une erreur distincte indiquant “déjà utilisé”.

Attention

Ne laissez pas chaque worker rafraîchir indépendamment un jeton de rafraîchissement partagé. Désignez un unique propriétaire pour l’appel de rafraîchissement (un verrou autour du chemin de rafraîchissement, ou une routine dédiée) et faites relire aux autres workers le jeton d’accès résultant depuis le cache partagé, plutôt que de rafraîchir eux-mêmes.

Ce qui invalide un jeton avant l’heure

Aucun des événements ci-dessous ne révoque directement un jeton d’accès actif. Chacun bloque seulement quelque chose de nouveau (une nouvelle demande de jeton, ou le prochain rafraîchissement) pendant que le jeton d’accès déjà en main continue de fonctionner jusqu’à ce que sa propre TTL s’épuise.

Déclencheur	Effet
Le secret client de l’application OAuth est régénéré	Les nouvelles demandes de jeton ou de rafraîchissement utilisant l’ancien secret sont immédiatement rejetées. Un jeton d’accès déjà émis n’est pas affecté et continue de fonctionner jusqu’à expiration naturelle.
L’application OAuth ou son utilisateur de service est supprimé	Bloque l’émission de nouveaux jetons pour cette application. Les jetons déjà émis ne sont pas révoqués de manière proactive.
Les scopes de l’application OAuth sont modifiés	Un jeton d’accès déjà émis conserve ses scopes d’origine pour le reste de sa durée de vie. Le jeton n’adopte les nouveaux scopes qu’au prochain rafraîchissement ou à la prochaine émission.
La grant est explicitement révoquée	Bloque immédiatement la prochaine tentative de rafraîchissement. Le jeton d’accès toujours valide n’est pas expiré de force et continue de fonctionner jusqu’à expiration naturelle.

Note

La fenêtre d’exposition pratique après chacun de ces événements correspond à la TTL propre du jeton d’accès (environ une heure), pas à celle du jeton de rafraîchissement, puisqu’aucun d’eux ne touche un jeton déjà émis. Pour réduire cette fenêtre à zéro immédiatement, révoquez la grant et régénérez le secret ensemble, puis considérez l’intégration comme non autorisée jusqu’à ce qu’une TTL de jeton d’accès se soit écoulée.

Et ensuite ?

• Codes d’erreur pour le détail complet des réponses 401 et 403
• Flux Client Credentials, Flux pour application native ou Authorization Code + Custom Redirect Flow pour obtenir votre premier jeton