LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Perspectivas
Google Agenda
Participe da comunidade do SlackGoogle OAuth Token de atualização: Expiração, Limite de 7 Dias e Tempo de Vida Explicados (2026)
Os tokens de atualização do Google OAuth não duram para sempre. Entenda todas as condições de expiração - da armadilha de teste de 7 dias à regra de inatividade de 6 meses - e aprenda como manter sua integração com a API do Gmail ativa em produção.
import solicitações
# Trocar o token de atualização por um novo token de acesso
response = requests.post(
"https://oauth2.googleapis.com/token",
dados={
"id_do_cliente": "SEU_CLIENT_ID",
"client_secret": "SEU_SEGREDO",
"token_de_atualização": "1//0g...",
"grant_type": "token_de_atualização"
}
)
token = resposta.json()["token_de_acesso"]Unipile não armazena tokens OAuth em um arquivo paralelo ou cria cópias de dados independentes fora da sessão autenticada. As operações de armazenamento e atualização de tokens são escopadas exclusivamente à sessão de cada usuário autenticado quem concedeu explicitamente o acesso. Nenhum dado de token é compartilhado entre contas ou retido além do escopo de autorização definido pelo usuário.
Unipile atua como um intermediário técnico independente, realizando operações com a API do Gmail e tokens OAuth em nome de cada usuário autenticado que autorizou o acesso individualmente. A Unipile é não afiliado, endossado ou patrocinado pelo Google. Nenhuma credencial compartilhada é utilizada. Cada integração depende do consentimento OAuth próprio do usuário, emitido através do seu próprio projeto Google Cloud ou via fluxo OAuth certificado Nível 2 CASA da Unipile.
Unipile retransmite os limites de taxa e as restrições de cota da API do Google, conforme definido pelas políticas do Google. A cadência das solicitações, as decisões de volume e os padrões de uso permanecem uma decisão do lado do cliente. Os desenvolvedores são responsáveis por garantir que sua integração esteja em conformidade com os Termos de Serviço do Google, incluindo as políticas de manuseio de tokens OAuth e os escopos de acesso a dados. A Unipile fornece a infraestrutura - a conformidade com as políticas é responsabilidade de cada desenvolvedor.
O que é um token de atualização do Google OAuth?
Antes de mergulhar nas regras de expiração, é útil entender exatamente o que é um token de atualização do Google OAuth, o que ele faz e como ele difere de um token de acesso no fluxo do Google OAuth2.
A Token de atualização do Google OAuth é uma credencial de longa duração emitida pelo servidor de autorização do Google que permite que seu aplicativo obtenha novos tokens de acesso sem exigir que o usuário se autentique novamente. Ao contrário dos tokens de acesso (que expiram após 3.600 segundos), um token de atualização do Google OAuth persiste entre sessões — sujeito a condições específicas de expiração — e é emitido apenas quando o access_type=offline o parâmetro está incluído na solicitação de autorização.
O usuário autenticado aprova os escopos solicitados pelo seu aplicativo na tela de consentimento do Google. Com access_type=offline, o Google emite tanto um token de acesso quanto um token de atualização.
Os tokens de acesso têm um TTL fixo de 3.600 segundos. Após o vencimento, qualquer chamada à API retorna um erro 401 Não autorizado. Seu aplicativo deve trocar o token de atualização por um novo token de acesso.
Um POST para https://oauth2.googleapis.com/token com grant_type=refresh_token retorna um novo token de acesso. O token de atualização do OAuth do Google permanece válido (a menos que uma das 6 condições de expiração seja acionada).
access_type=offline deve ser definido
ya29.
1//
Os tokens de atualização do Google expiram? As 6 condições
Sim, um token de atualização do Google OAuth pode expirar – mas apenas sob condições específicas. Compreender todos os casos é crucial para qualquer API do Gmail integração que precisa ser executada sem supervisão. Aqui estão todos os seis cenários de expiração de token de atualização do Google OAuth que você deve lidar em produção.
| # | Condição | Quando dispara | Gravidade | Consertar |
|---|---|---|---|---|
| 1 | Aplicativo em modo de teste - Limite de 7 dias | A tela de consentimento do OAuth está em "Teste" e o aplicativo não é verificado pelo Google | Crítico | Publicar o app ou usar um app interno do Workspace |
| 2 | 6 meses de inatividade | O token não é usado para obter um token de acesso há 6 meses | Médio | Implemente pings de keep-alive; use token pelo menos a cada 6 meses |
| 3 | Usuário altera senha do Google | Afeta apenas tokens com escopos do Gmail ou de e-mail sensível | Médio | Reiniciar fluxo OAuth; solicitar reautorização |
| 4 | 50 tokens de atualização por par cliente-usuário | Usuário autoriza seu app mais de 50 vezes; tokens mais antigos são revogados silenciosamente | Médio | Guarde tokens no lado do servidor; nunca peça novamente, a menos que o token seja inválido |
| 5 | Usuário revoga acesso explicitamente | Usuário visita as configurações da Conta Google e remove seu aplicativo | Esperado | Pegar concessão_inválida; remover token armazenado; solicitar reautorização |
| 6 | Escopo sensível/restrito - aplicativo não verificado | Solicitação do aplicativo com escopos restritos sem passar pela verificação do Google | Crítico | Completo Verificação do Google OAuth ou limitar a escopos não sensíveis |
Ponto-chave: O limite de 7 dias (condição 1) é a causa mais comum de integrações quebradas durante o desenvolvimento. Ele se aplica apenas quando o status da tela de consentimento OAuth do seu app é "Testing" e o app NÃO foi enviado para verificação do Google. O Processo de verificação do Google OAuth é a correção permanente - mas leva tempo. Veja a seção 3 para soluções alternativas mais rápidas.
A armadilha dos 7 dias de teste: por que acontece, como escapar
A expiração de 7 dias do token de atualização do Google OAuth é o problema mais disruptivo que os desenvolvedores enfrentam durante a integração. Pega as equipes de surpresa: tudo funciona em desenvolvimento, os tokens param de ser atualizados exatamente 7 dias depois, e o resposta de erro aparece dias depois que o usuário autorizou o aplicativo.
Quando o status da tela de consentimento de um aplicativo está definido como "Teste" no Google Cloud Console, o Google a trata como um aplicativo não verificado. Para proteger os usuários, o Google expira automaticamente todos os tokens de atualização emitidos por aplicativos não verificados após exatamente 7 dias. Esta política está documentada na documentação do OAuth 2.0 do Google e se aplica independentemente de quantas vezes o usuário autorizou o aplicativo. O limite também se aplica a o limite de 100 usuários de teste para aplicativos em modo de teste. Uma vez que um token de atualização do Google OAuth expire sob esta regra, qualquer tentativa de usá-lo retorna concessão_inválida.
Altere o status da tela de consentimento OAuth do seu aplicativo de "Em teste" para "Em produção" no Google Cloud Console. Para aplicativos que solicitam escopos sensíveis ou restritos do Gmail, você deve completar o total Processo de verificação do aplicativo Google OAuth, incluindo uma auditoria de segurança. Uma vez publicado, A vida útil do token de atualização do Google OAuth torna-se indefinida (sujeito às 5 condições restantes).
Se seu aplicativo for usado apenas dentro de uma Organização do Google Workspace, defina o fluxo de consentimento do OAuth para o tipo de usuário "Interno". Aplicativos internos não estão sujeitos à expiração de 7 dias ou ao limite de 100 usuários de teste. Tokens emitidos para usuários do Workspace sob aplicativos internos não expiram com base na regra do modo de teste. Este é o caminho mais rápido para produtos B2B SaaS com clientes do Google Workspace.
A Unipile opera como um intermediário técnico independente em nome de cada usuário autenticado. Nosso fluxo OAuth possui certificação CASA Tier 2. Você pode testar com tokens não expirantes imediatamente enquanto os seus Verificação do Google OAuth está em andamento, depois mude para Bring-Your-Own-Credentials (BYOC) assim que aprovado. Sem limite de 7 dias durante sua fase de POC.
Crie sua integração com o Gmail hoje mesmo com tokens que não expiram após 7 dias. O Unipile lida com a atualização de tokens no lado do servidor.
Tempo de vida do token de atualização do Google OAuth em produção
Quando seu aplicativo for publicado e verificado, o tempo de vida do token de atualização do Google OAuth se torna efetivamente indefinido - mas com ressalvas importantes. As duas regras principais de produção são o limite de 50 tokens por cliente e usuário e a expiração por inatividade de 6 meses.
Um token de atualização do Google OAuth expira se não for usado para obter um novo token de acesso por 6 meses consecutivos. "Usado" significa uma chamada de atualização de token bem-sucedida - não uma chamada de API feita com o token de acesso resultante. Armazene tokens de atualização e agende atualizações silenciosas periódicas para mantê-los ativos. Um ping mensal para /token é suficiente.
Para aplicativos do Google Workspace com tipo de usuário "Interno", não há expiração de 7 dias nem requisito de verificação. Os tokens ainda observam a regra de inatividade de 6 meses e o Limite de 50 tokens por par cliente-usuário. Administradores do Workspace também podem revogar tokens em toda a organização através do Admin Console, o que substitui o gerenciamento de tokens no nível do aplicativo.
O Google permite um máximo de 50 tokens de atualização por combinação de ID do cliente OAuth + conta de usuário Google. Se seu aplicativo gerar um novo token de atualização (solicitando o usuário novamente com consentimento) além desse limite, o Google invalida silenciosamente o token mais antigo. Esta é uma causa comum de concessão_inválida erros em produção quando as equipes reautorizam usuários repetidamente durante fluxos de testes ou de reembarque. A correção é simples: armazene o token de atualização no lado do servidor e nunca solicite novamente, a menos que o token seja realmente inválido.
O que conta como "usar" um token de atualização OAuth2 do Google
Conta como uso: POST para https://oauth2.googleapis.com/token com grant_type=refresh_token que retorna um novo token de acesso
NÃO conta como uso: realizando chamadas para a API do Gmail com o token de acesso atual, mesmo milhões delas
NÃO conta como uso: chamando tokeninfo ou endpoints de introspecção - apenas o endpoint de troca de tokens reinicia o relógio de inatividade
Como atualizar um token de acesso: curl, Node.js, Python
Quando seu token de acesso expirar, você precisará trocar seu token de atualização do Google OAuth por um novo. Aqui estão exemplos de código prontos para produção para três ambientes comuns. Todos os três acessam o mesmo Endpoint de token do Google OAuth.
# Atualizar um token de acesso do Google OAuth usando o curl
enrolar -s -X POST \
"https://oauth2.googleapis.com/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=SEU_CLIENT_ID" \
-d "client_secret=SEU_CLIENT_SECRET" \
-d "refresh_token=SEU_REFRESH_TOKEN" \
-d "grant_type=refresh_token"
Resposta #: { "access_token": "ya29.XXX", "expires_in": 3600, "token_type": "Bearer" }import solicitações
import json
def atualizar_token_de_acesso_googletoken_de_atualização: str) -> str:
"Troque um token de atualização do Google OAuth por um novo token de acesso."
response = requests.post(
"https://oauth2.googleapis.com/token",
dados={
"id_do_cliente": "SEU_CLIENT_ID",
"client_secret": "SEU_CLIENT_SECRET",
"token_de_atualização": token_de_atualização,
"grant_type": "token_de_atualização",
},
)
dados = resposta.json()
se "erro" em dados
levantar Erro de valor(f"Falha na atualização do token: {data['error']} - {data.get('error_description')}")
return dados["token_de_acesso"]// Atualizar um token de acesso OAuth do Google - Node.js (fetch)
async function atualizar o token de acesso do Google(refreshToken) {
const params = new URLSearchParams({
client_id: "SEU_CLIENT_ID",
client_secret: "SEU_CLIENT_SECRET",
refresh_token: refreshToken,
grant_type: "token_de_atualização",
});
const res = await fetch("https://oauth2.googleapis.com/token", {
method: "POST",
cabeçalhos: { "Tipo-de-Conteúdo": "application/x-www-form-urlencoded" },
body: params.toString(),
});
const data = await res.json();
se (erro do dado) lançar novo Erro(`${data.error}: ${data.error_description}`);
return data.access_token; // válido por 3600s
}Teste interativamente: Use o Google OAuth Playground para testar o fluxo de token de atualização sem escrever nenhum código. Ele permite que você obtenha tokens, inspecione respostas e depure o ciclo de vida completo do token de atualização do Google OAuth2 em uma interface de navegador.
invalid_grant: guia rápido
Quando um token de atualização do Google OAuth expira, é revogado ou inválido, o endpoint de token retorna um concessão_inválida Erro. Este é o sinal canônico de que seu token de atualização OAuth do Google não é mais utilizável. Aqui estão as causas mais comuns e suas correções imediatas.
App está com o status "Testing". Token expirou após 7 dias. Correção: publique o app ou mude para Workspace interno.
Token não usado por 6 meses. Correção: implementar atualização keep-alive; agendar troca mensal de token.
Consentimento concedido muitas vezes; token mais antigo revogado silenciosamente. Correção: armazene tokens no lado do servidor, nunca solicite novamente desnecessariamente.
Usuário removeu seu aplicativo das configurações da Conta Google. Correção: excluir token armazenado; exibir solicitação de reautorização ao usuário.
Usuário trocou a senha do Google enquanto seu aplicativo detém escopos sensíveis do Gmail. Correção: capturar erro, solicitar reautorização.
ID/segredo do cliente incompatíveis, ou o token foi emitido por um aplicativo diferente. Correção: verifique as credenciais; teste com o OAuth Playground.
Para uma análise completa de cada código de erro do Google OAuth com status HTTP, tabela de causas e correções em nível de código, consulte a análise completa Guia de referência de erros do Google OAuth.
Tokens de atualização gerenciados com Unipile
Construir e manter um ciclo de vida robusto de token de atualização do Google OAuth é um trabalho de engenharia não trivial. A Unipile atua como um intermediário técnico independente em nome de cada usuário autenticado, tratando do armazenamento de token, agendamento de refresh e recuperação de erros no lado do servidor - para que sua equipe entregue funcionalidades em vez de depurar concessão_inválida às 2 da manhã.
Unipile armazena os tokens de atualização dos seus usuários criptografados no lado do servidor e atualiza proativamente os tokens de acesso antes que expirem. Nenhum erro 401 chega à sua aplicação.
O aplicativo OAuth próprio da Unipile passou na avaliação de segurança Tier 2 da CASA. Durante o seu POC, seus usuários autorizam através do fluxo verificado da Unipile - nenhum limite de teste de 7 dias se aplica.
Quando sua própria verificação do Google OAuth for aprovada, mude para o modo BYOC: seus usuários autorizam através do seu próprio aplicativo Google verificado, enquanto o Unipile continua gerenciando a infraestrutura de atualização de tokens.
Unipile fornece um único API do Gmail camada de abstração que também cobre Outlook (Microsoft 365 + Exchange Online) e IMAP – cada um com seu próprio ciclo de vida de token gerenciado, para que você nunca precise implementar lógica de atualização específica do provedor.
POC com chave Unipile: Conecte seus primeiros usuários autenticados imediatamente através do fluxo CASA Tier 2 da Unipile. Sem expiração de 7 dias. Acesso completo à API do Gmail através do endpoint unificado da Unipile.
Certificar em paralelo: Envie seu próprio aplicativo Google para verificação OAuth enquanto executa sua integração em produção. O Unipile suporta essa trilha paralela.
Mude para BYOC: Assim que o Google aprovar seu aplicativo, ative o modo "Bring-Your-Own-Credentials". A vida útil do seu token de atualização do Google OAuth se torna indefinida em produção. O Unipile continua gerenciando a infraestrutura de atualização.
#: Listar e-mails via Unipile — token de atualização gerenciado no servidor
import solicitações
cabeçalhos = {
"X-API-KEY": "SUA_CHAVE_DE_API_UNIPILE",
"aceitar": "application/json",
}
# account_id = ID da conta vinculada do usuário autenticado
response = requests.get(
"https://api7.unipile.com:13046/api/v1/emails",
parâmetros={"id_da_conta": "acc_XXXXXXXX"},
cabeçalhos=cabeçalhos,
)
O token de atualização do Google OAuth # é atualizado automaticamente pelo Unipile
emails = resposta.json()["itens"]Google OAuth Refresh Token - Perguntas Frequentes
Perguntas comuns sobre expiração, tempo de vida e o ciclo de vida do token de atualização do Google OAuth2.
Sim, sob 6 condições específicas. A mais comum é a Limite de teste de 7 diasse seu aplicativo estiver em status "Testing" no Google Cloud Console, todos os tokens de atualização expirarão após 7 dias. Em produção com um aplicativo verificado, os tokens são efetivamente permanentes, a menos que: (1) não sejam usados por 6 meses, (2) o usuário revogue o acesso, (3) a senha seja alterada com escopos do Gmail, (4) o limite de 50 tokens seja excedido, ou (5) o aplicativo perca a verificação para escopos sensíveis. Entendendo Verificação do Google OAuth é fundamental para evitar expirações inesperadas.
Tempo de vida do token de atualização do Google OAuth depende do status do seu aplicativo. Em modo de teste: 7 dias no máximo, independentemente do uso. Em produção (app verificado): sem expiração fixa - os tokens duram indefinidamente, desde que sejam usados pelo menos uma vez a cada 6 meses, o limite de 50 tokens não seja excedido e o usuário não tenha revogado o acesso. Aplicativos internos do Google Workspace também não têm limite de 7 dias.
O token de atualização do Google OAuth expiração de 7 dias aplica-se quando o status da sua tela de consentimento OAuth é "Testing" no Google Cloud Console. O Google impõe esse limite em todos os aplicativos não verificados como medida de segurança. Coincide também com o limite de 100 usuários de teste. A correção é publicar seu aplicativo e concluir a verificação do Google OAuth (para produção) ou definir o aplicativo como "Interno", se for apenas para o Workspace.
Para prevenir o token de atualização do google oauth2 para expirar devido a 6 meses de inatividade: agendar uma POSTagem mensal para https://oauth2.googleapis.com/token com grant_type=refresh_token. Isso redefine o temporizador de inatividade. Observe que fazer chamadas à API do Gmail com um token de acesso existente NÃO conta como "usar" o token de atualização – apenas o endpoint de troca de token redefine o temporizador. Armazene os tokens no lado do servidor e nunca solicite novamente aos usuários desnecessariamente para permanecer abaixo do limite de 50 tokens.
concessão_inválida significa seu expiração do token de atualização do Google OAuth foi acionado ou o token é inválido. Causas principais: token expirado (limite de teste de 7 dias ou inatividade de 6 meses), usuário revogou o acesso nas configurações da Conta do Google, o limite de 50 tokens por cliente/usuário foi excedido e este token foi deslocado, alteração de senha com escopos do Gmail ou credenciais de cliente incompatíveis. Veja o completo Guia de erros do Google OAuth para etapas detalhadas de remediação por causa.
Você não pode obter um novo token de atualização do Google OAuth sem interação do usuário - por design. Tokens de atualização são emitidos apenas durante o fluxo de autorização de consentimento do usuário. Se seu token expirou ou foi revogado, você deve redirecionar o usuário pelo fluxo OAuth novamente. Adicionando consentimento força uma nova tela de consentimento e emite um novo token, mas conta para o limite de 50 tokens. A melhor prática é prevenir a expiração em primeiro lugar: armazene tokens com segurança, implemente atualizações "keep-alive" e lide com concessão_inválida trata erros graciosamente, solicitando nova autorização apenas quando necessário.
POST para https://oauth2.googleapis.com/token com Tipo de Conteúdo: application/x-www-form-urlencoded e parâmetros de corpo: id_cliente, segredo_do_cliente, token_de_atualizaçãoe grant_type=refresh_token. A resposta retorna um novo token_de_acesso válido por 3.600 segundos. Se a resposta contiver "erro": "grant_invalido", o token de atualização da API do Google não é mais válido e uma reautorização do usuário é necessária. Veja os exemplos de código na seção 5 para implementações com curl, Python e Node.js.
Ainda tem dúvidas sobre tokens de atualização do Google OAuth? Nossa equipe está aqui para ajudar.
BR 
EN 
FR 
ES 
DE 
IT 
NL 
PL 
TR