LinkedIn
Instagram
WhatsApp
Telegramma
Gmail
Prospettiva
Calendario di Google
Partecipare alla comunità SlackGoogle OAuth Gettone di aggiornamento: Scadenza, Limite di 7 Giorni e Durata Illimitata Spiegati (2026)
I token di aggiornamento di Google OAuth non durano per sempre. Comprendi ogni condizione di scadenza, dalla trappola dei test di 7 giorni alla regola dell'inattività di 6 mesi, e scopri come mantenere attiva la tua integrazione con l'API Gmail in produzione.
import richieste
#: sostituisci il token di aggiornamento con un nuovo token di accesso
response = richieste.post(
"https://oauth2.googleapis.com/token",
dati={
"client_id": "IL_TUO_CLIENT_ID",
"client_secret": "TUO_SEGRETO",
"token di aggiornamento": "1//0g...",
"grant_type": "token di aggiornamento"
}
)
token = risposta.json()["token_di_accesso"]Unipile non archivia i token OAuth in un archivio parallelo né crea copie di dati indipendenti al di fuori della sessione autenticata. Le operazioni di archiviazione e aggiornamento dei token sono limitate esclusivamente alla sessione di ciascun utente. utente autenticato chi ha concesso esplicitamente l'accesso. Nessun dato del token viene condiviso tra account né conservato oltre l'ambito di autorizzazione definito dall'utente.
Unipile funge da intermediario tecnico indipendente, eseguendo operazioni con le API di Gmail e i token OAuth per conto di ciascun utente autenticato che abbia autorizzato individualmente l'accesso. Unipile è non affiliato, approvato o sponsorizzato da Google. Nessuna credenziale condivisa viene utilizzata. Ogni integrazione si basa sul consenso OAuth dell'utente, rilasciato tramite il proprio progetto Google Cloud o tramite il flusso OAuth certificato CASA Tier 2 di Unipile.
Unipile ritrasmette i limiti di frequenza e le restrizioni di quota dell'API di Google come definiti dalle policy di Google. La cadenza delle richieste, le decisioni sul volume e i pattern di utilizzo rimangono una decisione lato cliente. Gli sviluppatori sono responsabili di garantire che la loro integrazione sia conforme ai Termini di Servizio di Google, incluse le policy sulla gestione dei token OAuth e gli ambiti di accesso ai dati. Unipile fornisce l'infrastruttura; la conformità alle policy è responsabilità di ogni sviluppatore.
Che cos'è un token di aggiornamento OAuth di Google?
Prima di addentrarci nelle regole di scadenza, è utile capire esattamente cos'è un token di aggiornamento Google OAuth, cosa fa e in cosa differisce da un token di accesso nel flusso Google OAuth2.
A Token di aggiornamento OAuth di Google è una credenziale di lunga durata emessa dal server di autorizzazione di Google che consente alla tua applicazione di ottenere nuovi token di accesso senza richiedere all'utente di autenticarsi nuovamente. A differenza dei token di accesso (che scadono dopo 3.600 secondi), un token di aggiornamento OAuth di Google persiste tra le sessioni - soggetto a specifiche condizioni di scadenza - e viene emesso solo quando access_type=offline il parametro è incluso nella richiesta di autorizzazione.
L'utente autenticato approva gli ambiti richiesti dalla tua app nella schermata di consenso di Google. Con access_type=offline, Google rilascia sia un token di accesso che un token di aggiornamento.
I token di accesso hanno una TTL fissa di 3.600 secondi. Una volta scaduti, qualsiasi chiamata API restituirà un errore 401 Unauthorized. La tua app deve scambiare il token di aggiornamento per un nuovo token di accesso.
Un POST a https://oauth2.googleapis.com/token con grant_type=refresh_token restituisce un nuovo token di accesso. Il token di aggiornamento OAuth di Google rimane valido (a meno che non si verifichino una delle 6 condizioni di scadenza).
access_type=offline deve essere impostato
ya29.
1//
I token di aggiornamento di Google scadono? Le 6 condizioni
Sì, un token di aggiornamento Google OAuth può scadere, ma solo in determinate condizioni. Comprendere ogni caso è fondamentale per qualsiasi API Gmail integrazione che deve essere eseguita in modo automatico. Ecco tutti e sei gli scenari di scadenza del token di aggiornamento OAuth di Google che è necessario gestire in produzione.
| # | Condizione | Quando spara | Gravità | Risolvi |
|---|---|---|---|---|
| 1 | App in modalità test - Limite di 7 giorni | La schermata di consenso OAuth è "In fase di test" e l'app non è verificata da Google | Critico | Pubblica l'app o usa un'app interna di Workspace |
| 2 | 6 mesi di inattività | Il token non è stato utilizzato per ottenere un token di accesso per 6 mesi | Medio | Implementa ping di keep-alive; usa il token almeno ogni 6 mesi |
| 3 | L'utente cambia la password di Google | Influisce solo sui token con ambiti di Gmail o posta sensibile | Medio | Ri-avviare il flusso OAuth; richiedi ri-autorizzazione |
| 4 | 50 token di aggiornamento per coppia client-utente | L'utente autorizza la tua app più di 50 volte; i token più vecchi vengono revocati silenziosamente | Medio | Archivia i token lato server; non richiedere mai una nuova richiesta a meno che il token non sia non valido |
| 5 | Utente revoca esplicitamente l'accesso | L'utente visita le impostazioni dell'Account Google e rimuove la tua app | Atteso | Prendi concessione_non_valida; rimuovi token memorizzato; richiedi ri-autorizzazione |
| 6 | Ambito sensibile/limitato - app non verificata | Richieste di app con ambiti limitati senza superare la verifica di Google | Critico | Completare Verifica Google OAuth o ridimensionare a ambiti non sensibili |
Spunto chiave: Il limite di 7 giorni (condizione 1) è la causa più comune di integrazioni interrotte durante lo sviluppo. Si applica solo quando lo stato della schermata di consenso OAuth della tua app è "In test" e l'app NON è stata inviata per la verifica di Google. Processo di verifica di Google OAuth è la soluzione permanente - ma richiede tempo. Vedere la sezione 3 per soluzioni alternative più rapide.
La trappola dei 7 giorni: perché succede, come uscirne
La scadenza di 7 giorni per il token di aggiornamento OAuth di Google è il problema più dirompente che gli sviluppatori incontrano durante l'integrazione. Cogli di sorpresa i team: tutto funziona in fase di sviluppo, i token smettono di aggiornarsi esattamente dopo 7 giorni e il risposta di errore spesso compare giorni dopo che l'utente ha autorizzato l'app.
Quando lo stato della schermata di consenso di un'app OAuth è impostato su "Test" nella Google Cloud Console, Google la tratta come un'applicazione non verificata. Per proteggere gli utenti, Google scade automaticamente tutti i token di aggiornamento emessi da app non verificate dopo esattamente 7 giorni. Questa policy è documentata nella documentazione di OAuth 2.0 di Google e si applica indipendentemente dal numero di volte in cui l'utente ha autorizzato l'app. Il limite si applica anche a il limite di 100 utenti di test per le app in modalità di test. Una volta che un token di aggiornamento OAuth di Google scade secondo questa regola, qualsiasi tentativo di utilizzarlo restituisce concessione_non_valida.
Cambia lo stato della schermata di consenso OAuth della tua app da "In test" a "In produzione" nella Google Cloud Console. Per le app che richiedono ambiti Gmail sensibili o riservati, devi completare il tutto Processo di verifica dell'app Google OAuth, inclusa una revisione della sicurezza. Una volta pubblicato, la durata del token di aggiornamento di Google OAuth diventa indefinita (soggetto alle restanti 5 condizioni).
Se la tua app viene utilizzata solo all'interno di un Organizzazione di Google Workspace, imposta il tipo di schermo di consenso OAuth su "Interno". Le app interne non sono soggette alla scadenza di 7 giorni o al limite di 100 utenti di test. I token emessi agli utenti di Workspace con app interne non scadono in base alla regola della modalità di test. Questo è il percorso più veloce per i prodotti SaaS B2B con clienti Google Workspace.
Unipile opera come un intermediario tecnico indipendente per conto di ciascun utente autenticato. Il nostro flusso OAuth è certificato CASA Tier 2. Puoi testare immediatamente con token non scaduti mentre la tua Verifica Google OAuth è in corso, quindi passare a Bring-Your-Own-Credentials (BYOC) una volta approvato. Nessun limite di 7 giorni durante la tua fase di POC.
Costruisci oggi la tua integrazione Gmail con token che non scadono dopo 7 giorni. Unipile gestisce il refresh dei token lato server.
Durata del token di aggiornamento OAuth di Google in produzione
Una volta che la tua app è pubblicata e verificata, la durata del token di aggiornamento di Google OAuth diventa effettivamente indefinita, ma con importanti avvertenze. Le due regole fondamentali di produzione sono il limite di 50 token per client-utente e la scadenza per inattività di 6 mesi.
Un token di aggiornamento OAuth di Google scade se non è stato utilizzato per ottenere un nuovo token di accesso per 6 mesi consecutivi. "Usato" significa una chiamata di aggiornamento del token andata a buon fine, non una chiamata API effettuata con il token di accesso risultante. Archivia i token di aggiornamento e pianifica aggiornamenti silenziosi periodici per mantenerli attivi. Un ping mensile per /token è sufficiente.
Per le app di Google Workspace con tipo utente "Interno", non ci sono né scadenze di 7 giorni né requisiti di verifica. I token rispettano ancora la regola di inattività di 6 mesi e il Limite di 50 token per coppia client-utente. Gli amministratori dello spazio di lavoro possono anche revocare i token a livello di organizzazione tramite la Console di amministrazione, che sovrascrive la gestione dei token a livello di applicazione.
Google permette un massimo di 50 token di aggiornamento per combinazione di ID client OAuth + account utente Google. Se la tua app genera un nuovo token di aggiornamento (richiedendo nuovamente all'utente con consenso) oltre questo limite, Google invalida silenziosamente il token più vecchio. Questa è una causa comune di concessione_non_valida errori in produzione quando i team autorizzano ripetutamente gli utenti durante i flussi di test o di ripristino dell'onboarding. La soluzione è semplice: memorizzare il token di aggiornamento lato server e non richiedere mai di nuovo l'autorizzazione a meno che il token non sia effettivamente non valido.
Cosa si intende per "utilizzo" di un token di aggiornamento Google OAuth2:
Contano come uso: POST a https://oauth2.googleapis.com/token con grant_type=refresh_token che restituisce un nuovo token di accesso
NON conta come utilizzo: effettuare chiamate all'API di Gmail con il token di accesso corrente, anche milioni di esse
NON conta come utilizzo: chiamando tokeninfo o endpoint di introspezione: solo l'endpoint di scambio di token reimposta l'orologio di inattività
Come aggiornare un token di accesso: curl, Node.js, Python
Quando il tuo token di accesso scade, devi scambiare il tuo token di aggiornamento OAuth di Google per uno nuovo. Ecco esempi di codice pronti per la produzione per tre ambienti comuni. Tutti e tre accedono allo stesso Endpoint del token OAuth di Google.
# Aggiornamento di un token di accesso OAuth di Google tramite curl
ricciolo -s -X POST \
"https://oauth2.googleapis.com/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=IL_TUO_CLIENT_ID" \
-d "client_secret=IL_TUO_CLIENT_SECRET" \
-d "token_di_aggiornamento=IL_TUO_TOKEN_DI_AGGIORNAMENTO" \
-d "grant_type=refresh_token"
Risposta #: { "access_token": "ya29.XXX", "expires_in": 3600, "token_type": "Bearer" }import richieste
import json
def aggiorna_token_accesso_google(refresh_token: strada) -> strada:
"Scambiare un token di refresh OAuth di Google per un nuovo token di accesso."
response = richieste.post(
"https://oauth2.googleapis.com/token",
dati={
"client_id": "IL_TUO_CLIENT_ID",
"client_secret": "IL_TUO_SEGRETO_CLIENT",
"token di aggiornamento": token_di_aggiornamento,
"grant_type": "token di aggiornamento",
},
)
dati = risposta.json()
se "errore" in dati
salire Valore errato(f"Aggiornamento del token non riuscito: {data['error']} - {data.get('error_description')}")
return dati["token_di_accesso"]// Aggiorna un token di accesso OAuth di Google - Node.js (fetch)
async function aggiornaTokenAccessoGoogle(refreshToken) {
const parametri = new URLSearchParams({
client_id: "IL_TUO_CLIENT_ID",
client_secret: "IL_TUO_SEGRETO_CLIENT",
token_di_aggiornamento: refreshToken,
tipo_di_concessione: "token di aggiornamento",
});
const ris = await fetch("https://oauth2.googleapis.com/token", {
method: "POST",
intestazioni: { "Content-Type": "application/x-www-form-urlencoded" },
body: params.toString(),
});
const dati = await res.json();
se (errore.dati) lancia nuovo Errore(`${data.error}: ${data.error_description}`);
return data.access_token; // valido per 3600s
}Prova interattivamente: Utilizzare il Google OAuth Playground per testare il flusso del token di aggiornamento senza scrivere codice. Ti permette di ottenere token, ispezionare le risposte e fare il debug dell'intero ciclo di vita del token di aggiornamento oauth2 di Google in un'interfaccia utente del browser.
invalid_grant: guida rapida
Quando un token di aggiornamento OAuth di Google è scaduto, revocato o non valido, l'endpoint del token restituisce un concessione_non_valida Errore. Questo è il segno canonico che il tuo token di aggiornamento OAuth di Google non è più utilizzabile. Ecco le cause più comuni e le relative soluzioni immediate.
L'app è in stato "Testing". Il token è scaduto dopo 7 giorni. Soluzione: pubblica l'app o passa a Workspace interno.
Token non utilizzato per 6 mesi. Soluzione: implementare refresh keep-alive; pianificare scambio token mensile.
L'utente ha acconsentito troppe volte; il token più vecchio è stato revocato silenziosamente. Soluzione: archiviare i token lato server, non richiedere nuovamente inutilmente.
L'utente ha rimosso la tua app dalle impostazioni dell'Account Google. Correzione: elimina il token memorizzato; mostra all'utente un invito alla riautorizzazione.
L'utente ha cambiato la password di Google mentre la tua app detiene ambiti sensibili di Gmail. Correzione: gestisci l'errore, richiedi la riautorizzazione.
ID client/segreto non corrispondenti, o il token è stato emesso da un'app diversa. Soluzione: verificare le credenziali; testare con il OAuth Playground.
Per una spiegazione completa di ogni codice di errore di Google OAuth con stato HTTP, tabella delle cause e soluzioni a livello di codice, consulta l'intero Guida di riferimento agli errori di Google OAuth.
Gestione dei token di aggiornamento con Unipile
Costruire e mantenere un ciclo di vita robusto del token di aggiornamento di Google OAuth è un lavoro di ingegneria non banale. Unipile agisce come un intermediario tecnico indipendente per conto di ogni utente autenticato, gestendo l'archiviazione dei token, la pianificazione del refresh e il recupero degli errori lato server, così il tuo team rilascia funzionalità invece di eseguire il debug concessione_non_valida alle 2 del mattino.
Unipile memorizza i token di aggiornamento dei tuoi utenti crittografati lato server e rinnova proattivamente i token di accesso prima che scadano. Nessun errore 401 raggiunge la tua applicazione.
L'applicazione OAuth di Unipile ha superato la valutazione di sicurezza CASA Tier 2. Durante il tuo POC, i tuoi utenti autorizzano tramite il flusso verificato di Unipile, senza limiti di test di 7 giorni.
Quando la tua verifica Google OAuth sarà approvata, passa alla modalità BYOC: i tuoi utenti autorizzano tramite la tua app Google verificata, mentre Unipile continua a gestire l'infrastruttura di aggiornamento del token.
Unipile fornisce un singolo API Gmail strato di astrazione che copre anche Outlook (Microsoft 365 + Exchange Online) e IMAP, ognuno con il proprio ciclo di vita del token gestito, in modo da non dover mai implementare la logica di aggiornamento specifica del provider.
POC con chiave Unipile: Collega subito i tuoi primi utenti autenticati tramite il flusso CASA Tier 2 di Unipile. Nessuna scadenza di 7 giorni. Accesso completo all'API di Gmail tramite l'endpoint unificato di Unipile.
Certifica in parallelo: Invia la tua app Google per la verifica OAuth mentre esegui la tua integrazione in produzione. Unipile supporta questo percorso parallelo.
Passa a BYOC: Una volta che Google approva la tua app, attiva la modalità "Porta le tue credenziali". La durata del tuo token di aggiornamento OAuth di Google diventa illimitata in produzione. Unipile continua a gestire l'infrastruttura di aggiornamento.
# Elenco delle e-mail tramite Unipile - token di aggiornamento gestito lato server
import richieste
headers = {
"X-API-KEY": "LA_TUA_CHIAVE_API_UNIPILE",
"accettare": "application/json",
}
# account_id = ID dell'account collegato dell'utente autenticato
response = requests.get(
"https://api7.unipile.com:13046/api/v1/emails",
parametri={"account_id": "acc_XXXXXXXX"},
intestazioni=intestazioni,
)
Il token di aggiornamento OAuth # di Google viene aggiornato automaticamente da Unipile
email = risposta.json()["articoli"]Token di aggiornamento OAuth di Google - FAQ
Domande comuni sulla scadenza e sulla durata dei token di aggiornamento di Google OAuth, e sul ciclo di vita dei token di aggiornamento di Google OAuth 2.0.
Sì, a 6 condizioni specifiche. La più comune è la Limite di test di 7 giorni: se la tua app è nello stato "Testing" nella Google Cloud Console, tutti i token di aggiornamento scadono dopo 7 giorni. In produzione con un'app verificata, i token sono effettivamente permanenti a meno che: (1) non vengano utilizzati per 6 mesi, (2) l'utente revochi l'accesso, (3) la password venga modificata con gli ambiti Gmail, (4) venga superato il limite di 50 token o (5) l'app perda la verifica per ambiti sensibili. Comprendere Verifica Google OAuth è fondamentale per evitare scadenze impreviste.
Durata del token di aggiornamento di Google OAuth dipende dallo stato della tua app. In modalità di prova: 7 giorni massimo, indipendentemente dall'uso. In produzione (app verificata): nessuna scadenza fissa - i token durano indefinitamente purché vengano utilizzati almeno una volta ogni 6 mesi, non venga superato il limite di 50 token e l'utente non abbia revocato l'accesso. Anche le app interne di Google Workspace non hanno limiti di 7 giorni.
Il scadenza rinnovo token oauth google 7 giorni si applica quando lo stato della schermata di consenso OAuth è "Test" nella Google Cloud Console. Google impone questo limite a tutte le applicazioni non verificate come misura di sicurezza. Coincide anche con il 100 utenti di test limite. La soluzione consiste nel pubblicare la tua app e completare la verifica di Google OAuth (per la produzione) o impostare l'app su "Interno" se è esclusiva per Workspace.
Per prevenire il token di aggiornamento google oauth2 in scadenza per inattività di 6 mesi: pianifica un POST mensile per https://oauth2.googleapis.com/token con grant_type=refresh_token. Ciò reimposta il contatore di inattività. Tieni presente che effettuare chiamate all'API di Gmail con il token di accesso esistente NON conta come "utilizzo" del token di aggiornamento: solo l'endpoint di scambio di token reimposta il timer. Archivia i token sul lato server e non richiedere mai nuovamente agli utenti in modo non necessario per rimanere al di sotto del limite di 50 token.
concessione_non_valida significa tuo scadenza token di aggiornamento google oauth è stato attivato o il token non è valido. Cause principali: token scaduto (limite di test di 7 giorni o inattività di 6 mesi), l'utente ha revocato l'accesso dalle impostazioni dell'account Google, è stata superata la soglia di 50 token per client/utente e questo token è stato sostituito, cambio password con ambiti Gmail, o credenziali client non corrispondenti. Vedi la guida completa Guida agli errori di Google OAuth per passaggi di rimedio dettagliati per causa.
Non è possibile ottenere un nuovo token di aggiornamento OAuth di Google senza l'interazione dell'utente, per design. I token di aggiornamento vengono emessi solo durante il flusso di autorizzazione con consenso dell'utente. Se il tuo token è scaduto o revocato, devi reindirizzare nuovamente l'utente attraverso il flusso OAuth. Aggiungere consenso forza una nuova schermata di consenso ed emette un nuovo token, ma conta ai fini del limite di 50 token. La best practice è prevenire l'espirazione in primo luogo: archiviare i token in modo sicuro, implementare aggiornamenti keep-alive e gestire concessione_non_valida gestisce gli errori con grazia, richiedendo la ri-autorizzazione solo quando necessario.
POST a https://oauth2.googleapis.com/token con Content-Type: application/x-www-form-urlencoded e parametri del corpo: ID cliente, segreto del cliente, token_di_aggiornamento, e grant_type=refresh_token. La risposta restituisce un nuovo token_accesso valido per 3.600 secondi. Se la risposta contiene "errore": "invalid_grant", il token di aggiornamento di google api non è più valida ed è necessaria una nuova autorizzazione dell'utente. Fare riferimento ai campioni di codice nella sezione 5 per le implementazioni di curl, Python e Node.js.
Hai ancora domande sui token di aggiornamento di Google OAuth? Il nostro team è qui per aiutarti.
IT 
EN 
FR 
ES 
DE 
BR 
NL 
PL 
TR