LinkedIn
Instagram
WhatsApp
Telegram
Gmail
Outlook
Google Agenda
Rejoindre la communauté SlackGoogle OAuth Jeton de rafraîchissementExpiration, limite de 7 jours et durée de vie expliquées (2026)
Les jetons d'actualisation de l'OAuth de Google n'ont pas une durée de vie infinie. Comprenez toutes les conditions d'expiration, du piège des 7 jours de test à la règle d'inactivité de 6 mois, et apprenez à maintenir votre intégration de l'API Gmail active en production.
import demandes
# Échanger le jeton d'actualisation contre un nouveau jeton d'accès
response = requests.post(
"https://oauth2.googleapis.com/token",
données={
"identifiant_client": "VOTRE_CLIENT_ID",
"client_secret": "VOTRE_SECRET",
"jeton_rafraîchissement": "1//0g...",
"grant_type": "jeton_rafraîchissement"
}
)
jeton = réponse.json()["jeton_d'accès"]Unipile ne stocke pas les jetons OAuth dans une archive parallèle ni ne crée de copies de données indépendantes en dehors de la session authentifiée. Les opérations de stockage et d'actualisation des jetons sont exclusivement limitées à la session de chaque utilisateur authentifié qui a explicitement accordé l’accès. Aucune donnée de jeton n’est partagée entre les comptes ni conservée au-delà de la portée d’autorisation définie par l’utilisateur.
Unipile agit comme un intermédiaire technique indépendant, effectuer des opérations sur l'API Gmail et les jetons OAuth au nom de chaque utilisateur authentifié qui a individuellement autorisé l'accès. Unipile est n'est ni affilié à Google, ni approuvé par Google, ni parrainé par Google. Aucune information d'identification partagée n'est utilisée. Chaque intégration repose sur le consentement OAuth personnalisé de l'utilisateur, émis via son propre projet Google Cloud ou via le flux OAuth certifié CASA Tier 2 d'Unipile.
Unipile relaie les limites de taux et les restrictions de quota de l'API Google tels que définis par les politiques de Google. La cadence des requêtes, les décisions de volume et les modèles d'utilisation restent une décision côté client. Les développeurs sont responsables de s'assurer que leur intégration est conforme aux Conditions d'Utilisation de Google, y compris les politiques de gestion des jetons OAuth et les étendues d'accès aux données. Unipile fournit l'infrastructure – la conformité aux politiques relève de la responsabilité de chaque développeur.
Qu'est-ce qu'un jeton d'actualisation OAuth de Google ?
Avant de plonger dans les règles d'expiration, il est utile de comprendre exactement ce qu'est un jeton d'actualisation Google OAuth, ce qu'il fait et en quoi il diffère d'un jeton d'accès dans le flux Google OAuth2.
Une Jeton de rafraîchissement Google OAuth est un identifiant de longue durée émis par le serveur d'autorisation de Google qui permet à votre application d'obtenir de nouveaux jetons d'accès sans obliger l'utilisateur à se réauthentifier. Contrairement aux jetons d'accès (qui expirent après 3 600 secondes), un jeton d'actualisation OAuth Google persiste d'une session à l'autre - sous réserve de conditions d'expiration spécifiques - et n'est émis que lorsque type_accès=hors_ligne le paramètre est inclus dans la requête d'autorisation.
L'utilisateur authentifié approuve les champs d'application demandés par votre application sur l'écran de consentement de Google. Avec type_accès=hors_ligne, Google émet à la fois un jeton d'accès et un jeton de rafraîchissement.
Les jetons d'accès ont une durée de vie fixe de 3 600 secondes. Une fois expirés, tout appel API renvoie une erreur 401 non autorisée. Votre application doit échanger le jeton d'actualisation contre un nouveau jeton d'accès.
Un POST à https://oauth2.googleapis.com/token avec type_de_consentement=rafraîchir_jeton renvoie un nouveau jeton d'accès. Le jeton d'actualisation OAuth de Google reste quant à lui valide (à moins que l'une des six conditions d'expiration ne se produise).
type_accès=hors_ligne doit être réglé
29 ans.
1//
Les jetons d'actualisation Google expirent-ils ? Les 6 conditions
Oui, un jeton d'actualisation OAuth de Google peut expirer, mais uniquement dans des conditions spécifiques. Comprendre tous les cas est essentiel pour toute API Gmail intégration qui doit s'exécuter sans surveillance. Voici les six scénarios d'expiration de jeton d'actualisation Google OAuth que vous devez gérer en production.
| # | Condition | Quand il tire | Sévérité | Réparer |
|---|---|---|---|---|
| 1 | Application en mode test - limite de 7 jours | L'écran de consentement OAuth est en "mode test" et l'application n'est pas vérifiée par Google | Critique | Publier l'application ou utiliser une application Workspace interne |
| 2 | 6 mois d'inactivité | Le jeton n'a pas été utilisé pour obtenir un jeton d'accès depuis 6 mois | Moyen | Mettre en œuvre des pings de maintien de connexion ; utiliser le jeton au moins tous les 6 mois |
| 3 | L'utilisateur modifie le mot de passe Google | Ne concerne que les jetons ayant des scopes Gmail ou de courrier sensible | Moyen | Relancer le flux OAuth ; demander une nouvelle autorisation |
| 4 | 50 jetons de rafraîchissement par paire client-utilisateur | L'utilisateur autorise votre application plus de 50 fois ; les jetons les plus anciens sont révoqués silencieusement | Moyen | Stockez les jetons côté serveur ; ne redemandez jamais sauf si le jeton est invalide |
| 5 | L'utilisateur révoque explicitement l'accès | L'utilisateur accède aux paramètres du compte Google et supprime votre application | Attendue | Attraper grant_invalide; supprimer le jeton stocké ; inviter à une nouvelle autorisation |
| 6 | Portée sensible / restreinte - application non vérifiée | Les applications demandent des scopes restreints sans passer la vérification de Google | Critique | Compléter Vérification OAuth Google ou réduire à des périmètres non sensibles |
Insight clé : La limite de 7 jours (condition 1) est la cause la plus fréquente d'erreurs d'intégration lors du développement. Elle ne s'applique que lorsque le statut de l'écran de consentement OAuth de votre application est "En test" et que l'application N'A PAS été soumise pour vérification par Google. La Processus de vérification Google OAuth est la solution permanente - mais cela prend du temps. Voir la section 3 pour des solutions de contournement plus rapides.
Le piège des tests sur 7 jours : pourquoi il se produit, comment s'en sortir
L'expiration du jeton d'actualisation OAuth de Google après 7 jours est le problème le plus perturbant rencontré par les développeurs lors de l'intégration. Il prend les équipes par surprise : tout fonctionne en développement, les jetons cessent de se rafraîchir exactement 7 jours plus tard, et le réponse d'erreur apparaît souvent des jours après que l'utilisateur ait autorisé l'application.
Lorsque le statut de l'écran de consentement d'une application OAuth est défini sur "Test" Dans la console Google Cloud, Google la considère comme une application non vérifiée. Pour protéger les utilisateurs, Google expire automatiquement tous les jetons d'actualisation émis par des applications non vérifiées après exactement 7 jours. Cette politique est documentée dans la documentation OAuth 2.0 de Google et s'applique quel que soit le nombre de fois où l'utilisateur a autorisé l'application. Le plafond s'applique également à la limite de 100 utilisateurs de test pour les applications en mode test. Une fois qu'un jeton d'actualisation Google OAuth expire selon cette règle, toute tentative de l'utiliser renvoie grant_invalide.
Modifiez le statut de l'écran de consentement OAuth de votre application, de " En test " à " En production " dans la Google Cloud Console. Pour les applications demandant scopes Gmail sensibles ou restreints, vous devez accomplir le plein Processus de vérification de l'application Google OAuth, y compris un audit de sécurité. Une fois publié, La durée de vie du jeton de rafraîchissement de Google OAuth devient indéfinie sous réserve des 5 autres conditions.
Si votre application n'est utilisée qu'à l'intérieur d'un Organisation Google Workspace, définissez le type d'écran de consentement OAuth sur " Interne ". Les applications internes ne sont pas soumises à l'expiration de 7 jours ni au plafond de 100 utilisateurs de test. Les jetons émis aux utilisateurs de Workspace sous des applications internes n'expirent pas selon la règle du mode de test. C'est la voie la plus rapide pour les produits SaaS B2B avec des clients Google Workspace.
Unipile fonctionne en tant que intermédiaire technique indépendant pour le compte de chaque utilisateur authentifié. Notre flux OAuth est certifié CASA Tier 2. Vous pouvez tester avec des jetons non expirables immédiatement pendant que votre propre Vérification OAuth Google est en cours, puis basculez vers Bring-Your-Own-Credentials (BYOC) une fois approuvé. Aucune limite de 7 jours durant votre phase de POC.
Intégrez Gmail dès aujourd'hui avec des jetons qui n'expirent pas après 7 jours. Unipile gère le renouvellement des jetons côté serveur.
Durée de vie du jeton d'actualisation OAuth de Google en production
Une fois votre application publiée et vérifiée, la durée de vie du jeton d'actualisation Google OAuth devient effectivement illimitée, mais avec des mises en garde importantes. Les deux règles clés en production sont le plafond de 50 jetons par client et utilisateur et l'expiration après 6 mois d'inactivité.
Un jeton d'actualisation OAuth Google expire s'il n'a pas été utilisé pour obtenir un nouveau jeton d'accès pendant 6 mois consécutifs. " Utilisé " signifie un appel réussi de rafraîchissement de jeton - pas un appel d'API effectué avec le jeton d'accès résultant. Stockez les jetons de rafraîchissement et planifiez des rafraîchissements silencieux périodiques pour les maintenir actifs. Un ping mensuel vers /jeton est suffisant.
Pour les applications Google Workspace avec un type d'utilisateur "Interne", il n'y a pas d'expiration de 7 jours ni d'exigence de vérification. Les jetons respectent toujours la règle d'inactivité de 6 mois et le Limite de 50 jetons par paire client-utilisateur. Les administrateurs d'espace de travail peuvent également révoquer les jetons à l'échelle de l'organisation via la console d'administration, ce qui a priorité sur la gestion des jetons au niveau de l'application.
Google autorise un maximum de 50 jetons de rafraîchissement par combinaison d'ID client OAuth et de compte utilisateur Google. Si votre application génère un nouveau jeton d'actualisation (en demandant à nouveau à l'utilisateur avec consentement) au-delà de cette limite, Google invalide silencieusement le jeton le plus ancien. C'est une source courante de grant_invalide erreurs en production lorsque les équipes ré-autorisent de manière répétée les utilisateurs lors de tests ou de flux de ré-intégration. La solution est simple : stocker le jeton de rafraîchissement côté serveur et ne jamais demander à nouveau sauf si le jeton est réellement invalide.
Qu'est-ce qui est considéré comme une "utilisation" d'un jeton d'actualisation Google OAuth2 :
Compte comme une utilisation: POST à https://oauth2.googleapis.com/token avec type_de_consentement=rafraîchir_jeton qui renvoie un nouveau jeton d'accès
Ne compte PAS comme utilisation : effectuer des appels à l'API Gmail avec le jeton d'accès actuel, même des millions d'entre eux
Ne compte PAS comme utilisation : appel jetoninfo ou points de terminaison d'introspection - seul le point de terminaison d'échange de jeton réinitialise l'horloge d'inactivité
Comment actualiser un jeton d'accès : curl, Node.js, Python
Lorsque votre jeton d'accès expire, vous devez échanger votre jeton d'actualisation Google OAuth contre un nouveau. Voici des exemples de code prêts pour la production pour trois environnements courants. Tous les trois accèdent à la même Point de terminaison du jeton Google OAuth.
# Actualiser un jeton d'accès OAuth Google à l'aide de curl
curl curls -X POST \
"https://oauth2.googleapis.com/token" \
-H "Content-Type : application/x-www-form-urlencoded" \
-d "client_id=VOTRE_CLIENT_ID" \
-d "client_secret=VOTRE_CLIENT_SECRET" \
-d "refresh_token=VOTRE_REFRESH_TOKEN" \
-d "grant_type=refresh_token"
Réponse # : { "access_token": "ya29.XXX", "expires_in": 3600, "token_type": "Bearer" }import demandes
import json
déf rafraîchir_jeton_accès_googlejeton_rafraîchissement: chaîne) -> chaîne:
"Échanger un jeton de rafraîchissement OAuth Google contre un nouveau jeton d’accès."
response = requests.post(
"https://oauth2.googleapis.com/token",
données={
"identifiant_client": "VOTRE_CLIENT_ID",
"client_secret": "VOTRE_CLIENT_SECRET",
"jeton_rafraîchissement": jeton_rafraîchissement,
"grant_type": "jeton_rafraîchissement",
},
)
données = réponse.json()
si "erreur" en données
soulever Valeur d'erreur(f"Actualisation du jeton échouée : {data['error']} - {data.get('error_description')}")
return données["jeton_d'accès"]// Rafraîchir un jeton d'accès Google OAuth - Node.js (fetch)
async function actualiserJetonAccèsGoogle(refreshToken) {
const params = new URLSearchParams({
client_id : "VOTRE_CLIENT_ID",
client_secret : "VOTRE_CLIENT_SECRET",
jeton_actualisation : jetonActualisation,
type_accordé : "jeton_rafraîchissement",
});
const rés = await fetch("https://oauth2.googleapis.com/token", {
method: "POST",
headers : { "Content-Type": "application/x-www-form-urlencoded" },
body: params.toString(),
});
const données = await res.json();
si (data.erreur) lancer nouveau Erreur(`${data.error} : ${data.error_description}`);
return data.access_token; // valide pour 3600s
}Tester interactivement : Utiliser le Google OAuth Playground pour tester le flux de jeton de rafraîchissement sans écrire de code. Il vous permet d'obtenir des jetons, d'inspecter les réponses et de déboguer le cycle de vie complet du jeton de rafraîchissement Google OAuth2 dans une interface utilisateur de navigateur.
invalid_grant : guide rapide
Lorsque le jeton d'actualisation d'un jeton OAuth Google est expiré, révoqué ou invalide, le point de terminaison du jeton renvoie une grant_invalide Erreur. C'est le signe canonique que votre jeton de rafraîchissement Google OAuth n'est plus utilisable. Voici les causes les plus courantes et leurs solutions immédiates.
L'application est en statut "En test". Le jeton a expiré après 7 jours. Solution : publier l'application ou passer à un espace de travail interne.
Le jeton n'a pas été utilisé pendant 6 mois. Correction : implémenter un rafraîchissement "keep-alive" ; planifier un échange mensuel de jeton.
L'utilisateur a donné son consentement trop souvent ; le jeton le plus ancien a été révoqué sans avertissement. Solution : enregistrer les jetons côté serveur, ne jamais demander à nouveau le consentement sans raison valable.
L'utilisateur a supprimé votre application des paramètres de son compte Google. Correction : supprimer le jeton stocké ; afficher une invite de réautorisation à l'utilisateur.
L'utilisateur a changé son mot de passe Google alors que votre application détenait des autorisations Gmail sensibles. Solution : intercepter l'erreur, demander une ré-autorisation.
Identifiant client/secret non concordants, ou le jeton a été émis par une application différente. Correction : vérifiez les identifiants ; testez avec Aire de jeu OAuth.
Pour une explication complète de chaque code d'erreur Google OAuth avec le statut HTTP, le tableau des causes et les correctifs au niveau du code, consultez le Guide de référence sur les erreurs Google OAuth.
Tokens d'actualisation gérés avec Unipile
La création et la maintenance d'un cycle de vie de jeton d'actualisation Google OAuth solide représentent un travail d'ingénierie non négligeable. Unipile agit comme un intermédiaire technique indépendant pour le compte de chaque utilisateur authentifié, gérant le stockage des jetons, la planification de l'actualisation et la récupération d'erreurs côté serveur - pour que votre équipe déploie des fonctionnalités au lieu de déboguer grant_invalide à 2 heures du matin.
Unipile stocke les tokens de rafraîchissement de vos utilisateurs chiffrés côté serveur et rafraîchit proactivement les tokens d'accès avant leur expiration. Aucune erreur 401 n'atteint votre application.
L'application OAuth d'Unipile a réussi l'évaluation de sécurité CASA de niveau 2. Lors de votre POC, vos utilisateurs autorisent via le flux vérifié d'Unipile - aucune limite de test de 7 jours ne s'applique.
Une fois votre propre vérification Google OAuth approuvée, passez en mode BYOC : vos utilisateurs s'autorisent via votre propre application Google vérifiée, tandis qu'Unipile continue de gérer l'infrastructure de rafraîchissement des jetons.
Unipile fournit un seul API Gmail couche d'abstraction qui couvre également Outlook (Microsoft 365 + Exchange Online) et IMAP - chacun avec son propre cycle de vie de jeton géré, vous évitant ainsi de devoir implémenter une logique de rafraîchissement spécifique au fournisseur.
POC avec la clé Unipile : Connectez vos premiers utilisateurs authentifiés immédiatement via le flux CASA Tier 2 d'Unipile. Pas d'expiration de 7 jours. Accès complet à l'API Gmail via le point de terminaison unifié d'Unipile.
Certifier en parallèle : Soumettez votre propre application Google pour la vérification OAuth tout en exécutant votre intégration en production. Unipile prend en charge cette piste parallèle.
Passer à BYOC : Une fois que Google aura approuvé votre application, activez le mode "Bring-Your-Own-Credentials". La durée de vie de votre jeton d'actualisation Google OAuth deviendra indéfinie en production. Unipile continue de gérer l'infrastructure d'actualisation.
# : Récupération des e-mails via Unipile - gestion du jeton d'actualisation côté serveur
import demandes
en-têtes = {
"X-API-KEY": "VOTRE_CLE_API_UNIPILE",
"accepter": "application/json",
}
# account_id = identifiant du compte associé à l'utilisateur authentifié
response = requêtes.obtenir(
"https://api7.unipile.com:13046/api/v1/emails",
params={"account_id": "acc_XXXXXXXX"},
en-têtes=en-têtes,
)
Le jeton de rafraîchissement OAuth # de Google est rafraîchi automatiquement par Unipile
emails = réponse.json()["articles"]Google OAuth Refresh Token - FAQ
Questions fréquentes sur l'expiration et la durée de vie des jetons d'actualisation Google OAuth, et le cycle de vie des jetons d'actualisation Google OAuth2.
Oui, dans 6 conditions spécifiques. La plus fréquente est la Limite d'essai de 7 jours: si votre application est en statut " Testing " dans la console Google Cloud, tous les jetons d'actualisation expirent après 7 jours. En production avec une application vérifiée, les jetons sont effectivement permanents à moins que : (1) ils ne soient pas utilisés pendant 6 mois, (2) l'utilisateur ne révoque l'accès, (3) le mot de passe ne soit modifié avec des étendues Gmail, (4) un plafond de 50 jetons ne soit atteint, ou (5) l'application ne perde sa vérification pour des étendues sensibles. Comprendre Vérification OAuth Google est essentielle pour éviter les expirations inattendues.
Durée de vie du jeton d'actualisation Google OAuth dépend du statut de votre application. Dans mode test: 7 jours maximum, quel que soit l'usage. En production (application vérifiée): pas de date d'expiration fixe — les jetons restent valables indéfiniment tant qu'ils sont utilisés au moins une fois tous les six mois, que la limite de 50 jetons n'est pas dépassée et que l'utilisateur n'a pas révoqué l'accès. Les applications internes de Google Workspace ne sont pas non plus soumises à la limite de 7 jours.
Le expiration du jeton d'actualisation OAuth Google 7 jours s'applique lorsque le statut de votre écran de consentement OAuth est "En test" dans la console Google Cloud. Google applique cette limite à toutes les applications non vérifiées comme mesure de sécurité. Elle coïncide également avec Limite de 100 utilisateurs de test. La solution consiste à publier votre application et à terminer la vérification Google OAuth (pour la production) ou à définir l'application sur "Interne" si elle est réservée à Workspace.
Pour empêcher le Jeton d'actualisation Google OAuth2 date d'expiration en raison de 6 mois d'inactivité : planifiez un message POST mensuel pour https://oauth2.googleapis.com/token avec type_de_consentement=rafraîchir_jeton. Cela réinitialise le compte à rebours d'inactivité. Notez que les appels à l'API Gmail effectués avec le jeton d'accès existant ne sont PAS considérés comme une " utilisation " du jeton de rafraîchissement : seul le point de terminaison d'échange de jetons réinitialise le compte à rebours. Enregistrez les jetons côté serveur et ne demandez jamais inutilement aux utilisateurs de se reconnecter afin de rester en dessous de la limite de 50 jetons.
grant_invalide signifie le vôtre expiration du jeton de rafraîchissement OAuth de Google a été déclenchée ou le jeton est invalide. Causes principales : jeton expiré (limite d'essai de 7 jours ou inactivité de 6 mois), l'utilisateur a révoqué l'accès depuis les paramètres du compte Google, le plafond de 50 jetons par client-utilisateur a été dépassé et ce jeton a été déplacé, changement de mot de passe avec des scopes Gmail, ou identifiants client incompatibles. Voir le complet Guide des erreurs Google OAuth pour des étapes de remédiation détaillées par cause.
Vous ne pouvez pas obtenir un nouveau jeton d'actualisation OAuth Google sans interaction de l'utilisateur – c'est par conception. Les jetons d'actualisation ne sont émis que lors du flux d'autorisation avec consentement de l'utilisateur. Si votre jeton a expiré ou a été révoqué, vous devez à nouveau rediriger l'utilisateur vers le flux OAuth. Ajouter consentement affiche un nouvel écran de consentement et génère un nouveau jeton, mais cela est décompté du plafond de 50 jetons. La meilleure pratique consiste à éviter l'expiration dès le départ : stockez les jetons en toute sécurité, mettez en place des rafraîchissements de maintien de connexion et gérez grant_invalide gérer les erreurs avec élégance en demandant une ré-autorisation uniquement lorsque cela est nécessaire.
POST à https://oauth2.googleapis.com/token avec Content-Type : application/x-www-form-urlencoded et paramètres de corps : client_id, secret_client, token_rafraîchissement, ou encore type_de_consentement=rafraîchir_jeton. La réponse renvoie un nouvel access_token valable pendant 3 600 secondes. Si la réponse contient "erreur": "invalid_grant", le jeton d'actualisation de l'API Google n'est plus valide et une nouvelle autorisation de l'utilisateur est requise. Voir les exemples de code dans la section 5 pour les implémentations curl, Python et Node.js.
Toujours des questions sur les jetons de rafraîchissement Google OAuth ? Notre équipe est là pour vous aider.
FR 
EN 
ES 
DE 
IT 
BR 
NL 
PL 
TR