LinkedIn
Instagram
WhatsApp
Telegram
Gmail
Perspektywy
Kalendarz Google
Dołącz do społeczności SlackGoogle OAuth Token odświeżaniaWygaśnięcie, 7-dniowy limit i wieczność wyjaśnione (2026)
Tokeny odświeżania Google OAuth nie są wieczne. Poznaj wszystkie warunki wygaśnięcia - od 7-dniowej pułapki testowej po 6-miesięczną regułę braku aktywności - i dowiedz się, jak utrzymać integrację z Gmail API aktywną w środowisku produkcyjnym.
import żądania
# Wymień token odświeżający na nowy token dostępu
response = requests.post(
"https://oauth2.googleapis.com/token",
dane={
"client_id": "TWÓJ_IDENTYFIKATOR_KLIENTA",
"client_secret": "TWÓJ_SEKRET",
"token_odświeżający": "1//0g...",
"typ_grantu": "token_odświeżający"
}
)
token = odpowiedź.json()["token dostępu"]Unipile nie przechowuje tokenów OAuth w równoległym archiwum ani nie tworzy niezależnych kopii danych poza uwierzytelnioną sesją. Operacje przechowywania i odświeżania tokenów są ograniczone wyłącznie do sesji każdego uwierzytelniony użytkownik ktoś, kto jednoznacznie udzielił dostępu. Dane tokenów nie są współdzielone między kontami ani przechowywane poza zakresem autoryzacji zdefiniowanym przez użytkownika.
Unipile działa jako niezależny pośrednik techniczny, wykonywanie operacji na Gmail API i tokenach OAuth w imieniu każdy uwierzytelniony użytkownik, który indywidualnie autoryzował dostęp. Unipile to nie powiązane z Google, nie zatwierdzone ani sponsorowane przez Google. Nie udostępniono żadnych danych uwierzytelniających. Każda integracja opiera się na samodzielnej zgodzie Google OAuth użytkownika, wydanej za pośrednictwem własnego projektu Google Cloud lub poprzez certyfikowany przepływ OAuth Unipile CASA Tier 2.
Unipile przekazuje limity żądań i ograniczenia kwotowe Google API zgodnie z polityką Google. Częstotliwość żądań, decyzje dotyczące wolumenu i wzorce użytkowania pozostają w decyzja po stronie klienta. Deweloperzy są odpowiedzialni za zapewnienie zgodności ich integracji z Warunkami korzystania z usługi Google, w tym z zasadami obsługi tokenów OAuth i zakresami dostępu do danych. Unipile zapewnia infrastrukturę – zgodność z polityką jest odpowiedzialnością każdego dewelopera.
Czym jest token odświeżający Google OAuth?
Zanim zagłębimy się w zasady wygasania, warto zrozumieć, czym dokładnie jest token odświeżający Google OAuth, co robi i czym różni się od tokena dostępu w przepływie Google OAuth2.
A Google OAuth token odświeżania są długo danym poświadczeniem wydanym przez serwer autoryzacyjny Google, które pozwala Twojej aplikacji na uzyskanie nowych tokenów dostępu bez konieczności ponownego uwierzytelniania użytkownika. W przeciwieństwie do tokenów dostępu (które wygasają po 3600 sekundach), token odświeżający Google OAuth jest trwały w sesjach – z zastrzeżeniem określonych warunków wygaśnięcia – i jest wydawany dopiero przy typ_dostępu=offline parametr jest uwzględniony w żądaniu autoryzacyjnym.
Uwierzytelniony użytkownik zatwierdza żądane przez Twoją aplikację zakresy na ekranie zgody Google. Z typ_dostępu=offline, Google wydaje zarówno token dostępu, jak i token odświeżania.
Tokeny dostępu mają stały czas życia wynoszący 3600 sekund. Po wygaśnięciu każde wywołanie API zwróci błąd 401 Unauthorized. Twoja aplikacja musi wymienić token odświeżania na nowy token dostępu.
POST do https://oauth2.googleapis.com/token z grant_type=refresh_token zwraca nowy token dostępu. Sam token odświeżania Google OAuth pozostaje ważny (chyba że zajdzie jeden z 6 warunków wygaśnięcia).
typ_dostępu=offline musi być ustawione
ya29.
1//
Czy tokeny odświeżające Google wygasają? 6 warunków
Tak, odświeżający token Google OAuth może wygasnąć – ale tylko w określonych warunkach. Zrozumienie każdego przypadku jest kluczowe dla każdego Gmail API integracja, która musi działać bez nadzoru. Oto wszystkie sześć scenariuszy wygaśnięcia tokenu odświeżania Google OAuth, które musisz obsłużyć w środowisku produkcyjnym.
| # | Stan | Gdy to wystrzeli | Waga | Naprawić |
|---|---|---|---|---|
| 1 | Aplikacja w trybie testowym - limit 7 dni | Ekran zgody OAuth ma status "Testowanie", a aplikacja nie została zweryfikowana przez Google | Krytyczny | Opublikuj aplikację lub użyj wewnętrznej aplikacji Workspace |
| 2 | 6 miesięcy bezczynności | Token nie był używany do uzyskania tokenu dostępu przez 6 miesięcy | Średni | Zaimplementuj pingi keep-alive; używaj tokena co najmniej raz na 6 miesięcy |
| 3 | Użytkownik zmienia hasło do Google | Dotyczy tylko tokenów z zakresami Gmail lub poufnej poczty | Średni | Zainicjuj ponownie przepływ OAuth; wymuś ponowne uwierzytelnienie |
| 4 | 50 tokenów odświeżania na parę klient-użytkownik | Użytkownik autoryzuje Twoją aplikację ponad 50 razy; najstarsze tokeny zostały po cichu unieważnione | Średni | Przechowuj tokeny po stronie serwera; nigdy nie pytaj ponownie, chyba że token jest nieprawidłowy |
| 5 | Użytkownik wyraźnie odwołuje dostęp | Użytkownik odwiedza ustawienia Konta Google i usuwa Twoją aplikację | Oczekiwany | Złapać nieprawidłowe_poświadczenie; usuń zapisany token; ponów próbę autoryzacji |
| 6 | Ograniczony/wrażliwy zakres – aplikacja niezweryfikowana | Aplikacja żąda ograniczonych zakresów bez przejścia weryfikacji Google | Krytyczny | Ukończ Weryfikacja Google OAuth lub ograniczyć zakres do zakresów niepowodujących wrażenia |
Kluczowy wniosek 7-dniowy limit (warunek 1) jest najczęstszą przyczyną awarii integracji podczas tworzenia. Obowiązuje on tylko wtedy, gdy status ekranu zgody OAuth aplikacji to "Testowanie", a aplikacja NIE została przesłana do weryfikacji przez Google. Proces weryfikacji Google OAuth jest stałym rozwiązaniem – ale wymaga czasu. Szybkie obejścia znajdują się w sekcji 3.
7-dniowa pułapka testowania: dlaczego się zdarza, jak się z niej wydostać
7-dniowy okres wygaśnięcia tokenu odświeżania Google OAuth jest najbardziej problematyczną kwestią, z jaką borykają się programiści podczas integracji. Zaskakuje to zespoły: wszystko działa w fazie rozwoju, tokeny przestają się odświeżać dokładnie po 7 dniach, a odpowiedź błędu często pojawia się kilka dni po tym, jak użytkownik autoryzował aplikację.
Gdy status ekranu zgody OAuth aplikacji jest ustawiony na "Testowanie" W Google Cloud Console Google traktuje to jako niezweryfikowaną aplikację. Aby chronić użytkowników, Google automatycznie unieważnia wszystkie tokeny odświeżania wydane przez niezweryfikowane aplikacje po dokładnie 7 dni. Polityka ta jest udokumentowana w dokumentacji OAuth 2.0 firmy Google i obowiązuje niezależnie od tego, ile razy użytkownik autoryzował aplikację. Limit ma również zastosowanie do limit 100 użytkowników testowych dla aplikacji w trybie testowym. Gdy token odświeżania Google OAuth wygaśnie zgodnie z tą zasadą, każda próba jego użycia zwraca nieprawidłowe_poświadczenie.
Zmień status ekranu zgody OAuth swojej aplikacji z "Testowanie" na "W produkcji" w Google Cloud Console. Dla aplikacji żądających wrażliwe lub ograniczone zakresy Gmail, musisz ukończyć całość Proces weryfikacji aplikacji Google OAuth, w tym audyt bezpieczeństwa. Po publikacji, Czas życia tokena odświeżającego Google OAuth staje się nieograniczony (z zastrzeżeniem pozostałych 5 warunków).
Jeśli Twoja aplikacja jest używana tylko w Organizacja Google Workspace, ustaw ekran zgody OAuth dla typu użytkownika na "Wewnętrzny". Aplikacje wewnętrzne nie podlegają 7-dniowemu terminowi ważności ani limitowi 100 użytkowników testowych. Tokeny wydane użytkownikom Workspace w ramach aplikacji wewnętrznych nie wygasają zgodnie z zasadą trybu testowego. Jest to najszybsza ścieżka dla produktów SaaS typu B2B z klientami Google Workspace.
Unipile działa jako niezależny pośrednik techniczny w imieniu każdy uwierzytelniony użytkownik. Nasz przepływ OAuth posiada certyfikat CASA Tier 2. Możesz od razu testować z niewygasającymi tokenami, podczas gdy Twoje własne Weryfikacja Google OAuth jest w toku, następnie przełącz się na Bring-Your-Own-Credentials (BYOC) po zatwierdzeniu. Bez 7-dniowego limitu w fazie Proof of Concept.
Zbuduj swoją integrację z Gmail już dziś dzięki tokenom, które nie wygasają po 7 dniach. Unipile obsługuje odświeżanie tokenów po stronie serwera.
Żywotność tokenu odświeżania Google OAuth w środowisku produkcyjnym
Gdy Twoja aplikacja zostanie opublikowana i zweryfikowana, okres ważności tokenów odświeżania OAuth Google staje się praktycznie nieograniczony – ale z ważnymi zastrzeżeniami. Dwie kluczowe zasady produkcyjne to limit 50 tokenów na klienta/użytkownika oraz wygaszenie z powodu braku aktywności przez 6 miesięcy.
token odświeżania OAuth Google wygasa, jeśli nie został użyty do uzyskania nowego tokenu dostępu przez 6 kolejnych miesięcy. "Użyty" oznacza udane wywołanie odświeżenia tokenu – nie wywołanie API dokonane przy użyciu wynikowego tokenu dostępu. Przechowuj tokeny odświeżania i zaplanuj okresowe ciche odświeżanie, aby utrzymać je przy życiu. Miesięczne pingnięcie do /token jest wystarczający.
W przypadku aplikacji Google Workspace z typem użytkownika "Wewnętrzny" nie ma 7-dniowego terminu ważności ani wymogu weryfikacji. Tokeny nadal podlegają zasadzie 6-miesięcznej nieaktywności i Limit 50 tokenów na parę klient-użytkownik. Administratorzy przestrzeni roboczej mogą również cofnąć tokeny w całej organizacji za pośrednictwem Konsoli administratora, co unieważnia zarządzanie tokenami na poziomie aplikacji.
Google pozwala na maksymalnie 50 tokenów odświeżania na identyfikator klienta OAuth + konto użytkownika Google. Jeśli Twoja aplikacja generuje nowy token odświeżający (ponownie prezentując użytkownikowi zgoda) poza tym limitem, Google po cichu unieważnia najstarszy token. Jest to częste źródło nieprawidłowe_poświadczenie błędy w produkcji, gdy zespoły wielokrotnie ponownie autoryzują użytkowników podczas testów lub ponownych wdrożeń. Rozwiązanie jest proste: przechowuj token odświeżania po stronie serwera i nigdy nie proś ponownie, chyba że token jest faktycznie nieprawidłowy.
Co liczy się jako "używanie" tokena odświeżającego Google OAuth2:
Użyte: POST do https://oauth2.googleapis.com/token z grant_type=refresh_token który zwraca nowy token dostępu
NIE wlicza się do użycia: wykonywanie wywołań do Gmail API za pomocą bieżącego tokenu dostępu, nawet milionów z nich
NIE wlicza się do użycia: dzwonienie informacjetokenu lub punkty introspekcji - tylko punkt wymiany tokenów resetuje zegar nieaktywności
Jak odświeżyć token dostępu: curl, Node.js, Python
Gdy Twój token dostępu wygaśnie, musisz wymienić swój token odświeżający Google OAuth na nowy. Oto gotowe do produkcji próbki kodu dla trzech popularnych środowisk. Wszystkie trzy korzystają z tego samego Punkt końcowy tokenów Google OAuth.
# Odśwież token dostępu Google OAuth za pomocą curl
zwijać się -s -X POST \
"https://oauth2.googleapis.com/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=TWÓJ_CLIENT_ID" \
-d "client_secret=TWÓJ_CLIENT_SECRET" \
-d "refresh_token=TWÓJ_TOKEN_ODŚWIEŻANIA" \
-d "grant_type=refresh_token"
Odpowiedź #: { "access_token": "ya29.XXX", "expires_in": 3600, "token_type": "Bearer" }import żądania
import json
def odśwież_token_dostępu_google(token_odświeżający: str) -> str:
"Wymiana odświeżającego tokena Google OAuth na nowy token dostępowy."
response = requests.post(
"https://oauth2.googleapis.com/token",
dane={
"client_id": "TWÓJ_IDENTYFIKATOR_KLIENTA",
"client_secret": "TWÓJ_SEKRETNY_KLUCZ",
"token_odświeżający"token_odświeżający,
"typ_grantu": "token_odświeżający",
},
)
dane = odpowiedź.json()
jeśli "błąd" w data
wzrastać ValueError(f"Niepowodzenie odświeżania tokenu: {data['error']} - {data.get('error_description')}")
return data["token dostępu"]// Odśwież token dostępu Google OAuth - Node.js (fetch)
async function odświeżGoogleAccessToken(refreshToken) {
const parametry = nowy URLSearchParams({
id_klienta: "TWÓJ_IDENTYFIKATOR_KLIENTA",
client_secret: "TWÓJ_SEKRETNY_KLUCZ",
token odświeżający: token odświeżający,
typ_udzielenia: "token_odświeżający",
});
const res = czekać fetch("https://oauth2.googleapis.com/token", {
method: "POST",
nagłówki: { "Content-Type": "application/x-www-form-urlencoded" },
body: params.toString(),
});
const dane = czekać rez.json();
jeśli (błąd.danych) rzuć nowy Błąd(`${data.error}: ${data.error_description}`);
return data.token_dostępu; // ważne przez 3600s
}Testuj interaktywnie: Użyj Plac zabaw Google OAuth aby przetestować przepływ odświeżania tokenu bez pisania kodu. Pozwala na uzyskiwanie tokenów, przeglądanie odpowiedzi i debugowanie pełnego cyklu życia tokenu odświeżania Google OAuth2 w interfejsie użytkownika przeglądarki.
invalid_grant: szybki przewodnik
Gdy token odświeżania Google OAuth jest wygasły, odwołany lub nieprawidłowy, punkt końcowy tokenu zwraca nieprawidłowe_poświadczenie Błąd. To standardowy znak, że Twój token odświeżania Google OAuth przestał być użyteczny. Oto najczęstsze przyczyny i ich natychmiastowe rozwiązania.
Aplikacja jest w stanie "Testowanie". Token wygasł po 7 dniach. Rozwiązanie: opublikuj aplikację lub przełącz się na wewnętrzne Obszar roboczy.
Token nieużywany przez 6 miesięcy. Rozwiązanie: zaimplementować odświeżanie na żywo; zaplanować miesięczną wymianę tokenów.
Użytkownik wyraził zgodę zbyt wiele razy; najstarszy token został po cichu unieważniony. Rozwiązanie: przechowuj tokeny po stronie serwera i nigdy nie wyświetlaj ponownie monitu bez konieczności.
Użytkownik usunął Twoją aplikację z ustawień Konta Google. Naprawa: usuń zapisany token; wyświetl użytkownikowi monit o ponowną autoryzację.
Użytkownik zmienił hasło do konta Google, podczas gdy Twoja aplikacja posiada uprawnienia dostępu do poufnych danych w Gmailu. Rozwiązanie: przechwyć błąd i poproś o ponowną autoryzację.
Niezgodność identyfikatora client_id i klucza tajnego lub token został wygenerowany przez inną aplikację. Rozwiązanie: sprawdź dane uwierzytelniające; przetestuj z Plac zabaw OAuth.
Aby uzyskać pełne zestawienie każdego kodu błędu Google OAuth wraz ze statusem HTTP, tabelą przyczyn i poprawkami na poziomie kodu, zobacz pełny Przewodnik referencyjny dotyczący błędów Google OAuth.
Zarządzane odświeżające tokeny za pomocą Unipile
Budowanie i utrzymywanie solidnego cyklu życia tokenów odświeżania Google OAuth jest niebanalnym zadaniem inżynieryjnym. Unipile działa jako niezależny pośrednik techniczny w imieniu każdy uwierzytelniony użytkownik, zarządzanie przechowywaniem tokenów, planowanie odświeżania i odzyskiwanie błędów po stronie serwera – dzięki czemu Twój zespół dostarcza funkcje, a nie debuguje nieprawidłowe_poświadczenie o 2 w nocy.
Unipile przechowuje tokeny odświeżające użytkowników zaszyfrowane po stronie serwera i proaktywnie odświeża tokeny dostępu przed ich wygaśnięciem. Żadne błędy 401 nie docierają do Twojej aplikacji.
Własna aplikacja OAuth Unipile przeszła ocenę bezpieczeństwa CASA Tier 2. Podczas Twojego POC, Twoi użytkownicy autoryzują się poprzez zweryfikowany przepływ Unipile – nie ma zastosowania 7-dniowy limit testowy.
Gdy Twoja własna weryfikacja Google OAuth zostanie zatwierdzona, przełącz się na tryb BYOC: Twoi użytkownicy będą się autoryzować za pośrednictwem Twojej własnej, zweryfikowanej aplikacji Google, a Unipile nadal będzie zarządzać infrastrukturą odświeżania tokenów.
Unipile zapewnia pojedynczy Gmail API warstwa abstrakcji, która obejmuje również Outlook (Microsoft 365 + Exchange Online) i IMAP – każdy z własnym zarządzanym cyklem życia tokenów, dzięki czemu nigdy nie implementujesz logiki odświeżania specyficznej dla dostawcy.
POC z kluczem Unipile: Natychmiast połącz swoich pierwszych uwierzytelnionych użytkowników za pomocą procesu CASA Tier 2 platformy Unipile. Bez 7-dniowego terminu ważności. Pełny dostęp do API Gmaila poprzez ujednolicony punkt końcowy platformy Unipile.
Certyfikuj równolegle: Prześlij własną aplikację Google do weryfikacji OAuth podczas uruchamiania integracji w środowisku produkcyjnym. Unipile obsługuje tę ścieżkę równoległą.
Zmień na BYOC: Gdy Google zatwierdzi Twoją aplikację, aktywuj tryb Bring-Your-Own-Credentials. Okres ważności Twojego tokena odświeżania Google OAuth staje się nieograniczony w środowisku produkcyjnym. Unipile nadal zarządza infrastrukturą odświeżania.
#: Wysyłanie list e-mailowych za pośrednictwem Unipile – token odświeżający obsługiwany po stronie serwera
import żądania
nagłówki = {
"X-API-KEY": "TWÓJ_KLUCZ_API_UNIPILE",
"akceptuj": "application/json",
}
# account_id = identyfikator połączonego konta uwierzytelnionego użytkownika
response = requests.get(
"https://api7.unipile.com:13046/api/v1/emails",
parametry={"account_id": "acc_XXXXXXXX"},
nagłówki=nagłówki,
)
Token odświeżający Google OAuth # jest odświeżany automatycznie przez Unipile
e-maile = odpowiedź.json()["przedmioty"]Token odświeżania Google OAuth - FAQ
Często zadawane pytania dotyczące wygasania, okresu ważności i cyklu życia tokenów odświeżania Google OAuth.
Tak, pod 6 konkretnymi warunkami. Najczęstszym jest 7-dniowy limit testowania: jeśli Twoja aplikacja jest w stanie "Testowanie" w Google Cloud Console, wszystkie tokeny odświeżania wygasają po 7 dniach. W produkcji w zweryfikowanej aplikacji tokeny są zasadniczo stałe, chyba że: (1) nie były używane przez 6 miesięcy, (2) użytkownik odwołał dostęp, (3) zmiana hasła w zakresach Gmail, (4) przekroczono limit 50 tokenów lub (5) aplikacja straciła weryfikację dla wrażliwych zakresów. Zrozumienie Weryfikacja Google OAuth jest kluczem do unikania nieoczekiwanych wygaśnięć.
Czas życia tokenu odświeżania Google OAuth zależy od statusu Twojej aplikacji. W tryb testowyMaksymalnie 7 dni, niezależnie od użytkowania. W produkcja (zweryfikowana aplikacja)brak stałej daty ważności - tokeny są ważne bezterminowo, dopóki są używane co najmniej raz na 6 miesięcy, nie przekroczono limitu 50 tokenów, a użytkownik nie cofnął dostępu. Aplikacje wewnętrzne Google Workspace również nie mają 7-dniowego limitu.
The Google OAuth odświeżanie tokenu 7-dniowy okres ważności dotyczy sytuacji, gdy status ekranu zgody OAuth jest ustawiony na "Testowanie" w Google Cloud Console. Google narzuca to ograniczenie na wszystkie niezweryfikowane aplikacje jako środek bezpieczeństwa. Zbiega się to również z 100 użytkowników testowych limit. Rozwiązaniem jest opublikowanie aplikacji i ukończenie weryfikacji Google OAuth (dla wersji produkcyjnej) lub ustawienie aplikacji jako "Wewnętrzna", jeśli jest przeznaczona tylko dla Workspace.
Aby zapobiec odświeżanie tokenu oauth2 google wygasające z powodu 6-miesięcznej bezczynności: zaplanuj miesięczny POST do https://oauth2.googleapis.com/token z grant_type=refresh_token. Resetuje to licznik nieaktywności. Zauważ, że wywoływanie interfejsu API Gmail za pomocą istniejącego tokena dostępu NIE liczy się jako "użycie" tokena odświeżania – tylko punkt końcowy wymiany tokena resetuje czasomierz. Przechowuj tokeny po stronie serwera i nigdy nie proś użytkowników ponownie o potwierdzenie, aby pozostać poniżej limitu 50 tokenów.
nieprawidłowe_poświadczenie oznacza twoje wygaśnięcie tokena odświeżania Google OAuth został wyzwolony lub token jest nieprawidłowy. Główne przyczyny: wygaśnięcie tokenu (limit testowy 7 dni lub 6 miesięcy braku aktywności), użytkownik odwołał dostęp w ustawieniach konta Google, przekroczono limit 50 tokenów na klienta/użytkownika i ten token został zastąpiony, zmiana hasła z zakresami Gmail, lub niedopasowane dane uwierzytelniające klienta. Zobacz pełny Przewodnik po błędach Google OAuth dla szczegółowych kroków naprawczych dla każdej przyczyny.
Nie można uzyskać nowego tokenu odświeżającego Google OAuth bez interakcji użytkownika – jest to zgodne z założeniami. Tokeny odświeżające są wydawane tylko podczas przepływu autoryzacji z zgodą użytkownika. Jeśli Twój token wygasł lub został unieważniony, musisz ponownie przekierować użytkownika przez przepływ OAuth. Dodanie zgoda wymusza nowy ekran zgody i wydaje nowy token, ale liczy się do limitu 50 tokenów. Najlepszą praktyką jest zapobieganie wygaśnięciu w pierwszej kolejności: bezpieczne przechowywanie tokenów, implementacja odświeżeń "keep-alive" i obsługa nieprawidłowe_poświadczenie obsługuje błędy w sposób zapobiegający awariom, inicjując ponowne uwierzytelnienie tylko wtedy, gdy jest to konieczne.
POST do https://oauth2.googleapis.com/token z Content-Type: application/x-www-form-urlencoded i parametry ciała: client_id, client_secret, token_odświeżającyoraz grant_type=refresh_token. Odpowiedź zwraca nowy token_dostępu ważne przez 3600 sekund. Jeśli odpowiedź zawiera "błąd": "nieprawidłowe_uprawnienie", the token odświeżający Google API nie jest już ważny i wymagane jest ponowne uwierzytelnienie użytkownika. Przykłady kodu w sekcji 5 dla implementacji curl, Python i Node.js.
Nadal masz pytania dotyczące tokenów odświeżania Google OAuth? Nasz zespół jest do Twojej dyspozycji.
PL 
EN 
FR 
ES 
DE 
IT 
BR 
NL 
TR