LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Outlook
Calendario de Google
Únase a la comunidad SlackGoogle OAuth Actualizar ficha: Caducidad, Límite de 7 Días y Explicación de Por Vida (2026)
Los tokens de actualización de Google OAuth no duran para siempre. Comprende todas las condiciones de expiración, desde la trampa de prueba de 7 días hasta la regla de inactividad de 6 meses, y aprende cómo mantener viva tu integración con la API de Gmail en producción.
import solicita
#: Cambiar el token de actualización por un nuevo token de acceso
response = requests.post(
"https://oauth2.googleapis.com/token",
datos={
"id_cliente": "TU_ID_DE_CLIENTE",
"secreto_del_cliente": "TU_SECRETO",
"token de actualización": "1//0g...",
"grant_type": "token de actualización"
}
)
token = respuesta.json()["token_de_acceso"]Unipile no almacena tokens OAuth en un archivo paralelo ni crea copias de datos independientes fuera de la sesión autenticada. Las operaciones de almacenamiento y actualización de tokens se limitan exclusivamente a la sesión de cada usuario. usuario autenticado quien ha concedido explícitamente el acceso. Los datos de los tokens no se comparten entre cuentas ni se conservan más allá del ámbito de autorización definido por el usuario.
Unipile actúa como un intermediario técnico independiente, realizando operaciones de la API de Gmail y tokens de OAuth en nombre de cada usuario autenticado que haya autorizado individualmente el acceso. Unipile es no afiliado con, avalado por, ni patrocinado por Google. No se comparten credenciales. Cada integración se basa en el consentimiento OAuth propio del usuario, emitido a través de su propio proyecto de Google Cloud o mediante el flujo OAuth certificado de Nivel 2 CASA de Unipile.
Unipile transmite los límites de tasa de la API de Google y las restricciones de cuota según lo definen las políticas de Google. La cadencia de las solicitudes, las decisiones de volumen y los patrones de uso siguen siendo una decisión del lado del cliente. Los desarrolladores son responsables de asegurar que su integración cumpla con los Términos de Servicio de Google, incluyendo las políticas de manejo de tokens OAuth y los alcances de acceso a datos. Unipile proporciona la infraestructura; el cumplimiento de las políticas es responsabilidad de cada desarrollador.
¿Qué es un token de actualización de Google OAuth?
Antes de sumergirse en las reglas de expiración, es útil comprender exactamente qué es un token de actualización de OAuth de Google, qué hace y en qué se diferencia de un token de acceso en el flujo de OAuth2 de Google.
A Token de actualización de Google OAuth es una credencial de larga duración emitida por el servidor de autorización de Google que permite a tu aplicación obtener nuevos tokens de acceso sin requerir que el usuario vuelva a autenticarse. A diferencia de los tokens de acceso (que caducan después de 3.600 segundos), un token de actualización de Google OAuth persiste entre sesiones —sujeto a condiciones específicas de caducidad— y se emite solo cuando el access_type=offline el parámetro está incluido en la solicitud de autorización.
El usuario autenticado aprueba los ámbitos solicitados por tu aplicación en la pantalla de consentimiento de Google. Con access_type=offline, Google emite tanto un token de acceso como un token de actualización.
Los tokens de acceso tienen un TTL fijo de 3600 segundos. Una vez caducados, cualquier llamada a la API devolverá un error 401 No autorizado. Tu aplicación debe canjear el token de actualización por un nuevo token de acceso.
Un POST a https://oauth2.googleapis.com/token con grant_type=refresh_token devuelve un nuevo token de acceso. El token de actualización de OAuth de Google en sí permanece válido (a menos que se cumpla alguna de las 6 condiciones de expiración).
access_type=offline debe ser ajustado
ya29.
1//
Los tokens de actualización de Google ¿expiran? Las 6 condiciones
Sí, un token de actualización de OAuth de Google puede expirar, pero solo bajo condiciones específicas. Comprender cada caso es fundamental para cualquier API de Gmail integración que necesita ejecutarse de forma desatendida. Aquí están los seis escenarios de expiración de tokens de actualización de Google OAuth que debes manejar en producción.
| # | Condición | Cuando dispara | Severidad | Arregla |
|---|---|---|---|---|
| 1 | Aplicación en modo de prueba - Límite de 7 días | La pantalla de consentimiento de OAuth está en "Pruebas" y la aplicación no está verificada por Google | Crítico | Publica la aplicación o utiliza una aplicación interna de Workspace |
| 2 | 6 meses de inactividad | El token no se ha utilizado para obtener un token de acceso durante 6 meses | Mediano | Implementar pings de keep-alive; usar el token al menos cada 6 meses |
| 3 | El usuario cambia la contraseña de Google | Solo afecta los tokens con ámbitos de Gmail o correo sensible | Mediano | Re-iniciar el flujo de OAuth; solicitar autorización de nuevo |
| 4 | 50 tokens de actualización por par cliente-usuario | El usuario autoriza tu aplicación más de 50 veces; los tokens más antiguos son revocados silenciosamente | Mediano | Almacena los tokens del lado del servidor; nunca vuelvas a solicitar a menos que el token sea inválido |
| 5 | El usuario revoca explícitamente el acceso | El usuario visita la configuración de la cuenta de Google y elimina tu aplicación | Es esperada | Atrapar concesión_inválida; eliminar token almacenado; solicitar nueva autorización |
| 6 | Alcance sensible/restringido - la aplicación no está verificada | La aplicación solicita alcances restringidos sin pasar la verificación de Google | Crítico | Completar Verificación de Google OAuth o limitar el alcance a ámbitos no sensibles |
Idea clave: El límite de 7 días (condición 1) es la causa más común de interrupciones en las integraciones durante el desarrollo. Solo se aplica cuando el estado de la pantalla de consentimiento OAuth de tu app es "Prueba" y la app NO se ha enviado para la verificación de Google. Proceso de verificación de Google OAuth es la solución permanente, pero lleva tiempo. Ver sección 3 para soluciones más rápidas.
La trampa de las pruebas de 7 días: por qué sucede, cómo escapar
La expiración de 7 días del token de actualización de Google OAuth es el problema más disruptivo que enfrentan los desarrolladores durante la integración. Coge a los equipos desprevenidos: todo funciona en el desarrollo, los tokens dejan de actualizarse exactamente 7 días después y el respuesta de error a menudo aparece días después de que el usuario autorizó la aplicación.
Cuando el estado de la pantalla de consentimiento OAuth de una aplicación se establece en "Prueba" En la Consola de Google Cloud, Google lo trata como una aplicación no verificada. Para proteger a los usuarios, Google expira automáticamente todos los tokens de actualización emitidos por aplicaciones no verificadas después de exactamente 7 días. Esta política está documentada en la documentación de OAuth 2.0 de Google y se aplica independientemente de cuántas veces el usuario haya autorizado la aplicación. El límite también se aplica a el límite de 100 usuarios de prueba para aplicaciones en modo de prueba. Una vez que un token de actualización de Google OAuth expira bajo esta regla, cualquier intento de usarlo devuelve concesión_inválida.
Cambia el estado de la pantalla de consentimiento OAuth de tu app de "Testing" a "En producción" en Google Cloud Console. Para las apps que solicitan ámbitos de Gmail sensibles o restringidos, debes completar el completo Proceso de verificación de la aplicación de Google OAuth, incluyendo una auditoría de seguridad. Una vez publicado, la vida útil del token de actualización de google oauth se vuelve indefinida (sujeto a las 5 condiciones restantes).
Si tu aplicación solo se usa dentro de un Organización de Google Workspace, configura la pantalla de consentimiento de OAuth en el tipo de usuario "Interno". Las aplicaciones internas no están sujetas a la expiración de 7 días ni al límite de 100 usuarios de prueba. Los tokens emitidos a los usuarios de Workspace bajo aplicaciones internas no caducan según la regla del modo de prueba. Este es el camino más rápido para los productos SaaS B2B con clientes de Google Workspace.
Unipile opera como un intermediario técnico independiente en nombre de cada usuario autenticado. Nuestro flujo OAuth tiene certificación CASA Nivel 2. Puedes probar con tokens no caducados inmediatamente mientras tus propios Verificación de Google OAuth está en curso, luego cambiar a Bring-Your-Own-Credentials (BYOC) una vez aprobado. Sin límite de 7 días durante tu fase de POC.
Construye tu integración de Gmail hoy con tokens que no caducan después de 7 días. Unipile maneja la actualización de tokens en el lado del servidor.
Tiempo de vida del token de actualización de Google OAuth en producción
Una vez que su aplicación se publica y verifica, la vida útil del token de actualización de Google OAuth se vuelve efectivamente indefinida, pero con advertencias importantes. Las dos reglas clave de producción son el límite de 50 tokens por cliente-usuario y la expiración por inactividad de 6 meses.
Un token de actualización de OAuth de Google expira si no se ha utilizado para obtener un nuevo token de acceso durante 6 meses consecutivos. "Usado" significa una llamada exitosa de actualización de token, no una llamada a la API realizada con el token de acceso resultante. Almacene los tokens de actualización y programe actualizaciones silenciosas periódicas para mantenerlos activos. Un ping mensual a /ficha es suficiente.
Para las aplicaciones de Google Workspace con tipo de usuario "Interno", no hay caducidad de 7 días ni requisito de verificación. Los tokens aún observan la regla de inactividad de 6 meses y la límite de 50 tokens por par cliente-usuario. Los administradores del espacio de trabajo también pueden revocar tokens en toda la organización a través de la Consola de administración, lo que anula la gestión de tokens a nivel de aplicación.
Google permite un máximo de 50 tokens de actualización por combinación de ID de cliente OAuth + cuenta de usuario de Google. Si tu aplicación genera un nuevo token de actualización (pidiendo de nuevo al usuario con consentimiento) más allá de este límite, Google invalida silenciosamente el token más antiguo. Esta es una fuente común de concesión_inválida errores en producción cuando los equipos reautorizan repetidamente a los usuarios durante las pruebas o los flujos de reincorporación. La solución es simple: almacene el token de actualización en el servidor y nunca vuelva a solicitarlo a menos que el token sea realmente inválido.
¿Qué cuenta como "usar" un token de actualización de OAuth2 de Google?:
Cuenta como uso: PUBLICAR a https://oauth2.googleapis.com/token con grant_type=refresh_token que devuelve un nuevo token de acceso
NO cuenta como uso: realizar llamadas a la API de Gmail con el token de acceso actual, incluso millones de ellas
NO cuenta como uso: llamando infoken o puntos de introspección; solo el punto final de intercambio de tokens reinicia el reloj de inactividad
Cómo actualizar un token de acceso: curl, Node.js, Python
Cuando tu token de acceso expire, deberás canjear tu token de actualización de Google OAuth por uno nuevo. Aquí tienes ejemplos de código listos para producción para tres entornos comunes. Los tres apuntan a lo mismo Punto final del token de Google OAuth.
#: Actualizar un token de acceso de Google OAuth con curl
rizo -s -X POST \
"https://oauth2.googleapis.com/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=TU_CLIENT_ID" \
-d "client_secret=TU_CLIENT_SECRET" \
-d "refrescar_token=TU_REFRESAR_TOKEN" \
-d "grant_type=refresh_token"
Respuesta de #: { "access_token": "ya29.XXX", "expires_in": 3600, "token_type": "Bearer" }import solicita
import json
def refrescar_token_acceso_googletoken_de_actualización: cadena) -> cadena:
"Intercambiar un token de actualización de Google OAuth por un nuevo token de acceso."
response = requests.post(
"https://oauth2.googleapis.com/token",
datos={
"id_cliente": "TU_ID_DE_CLIENTE",
"secreto_del_cliente": "TU_CLIENT_SECRET",
"token de actualización"token_de_actualización,
"grant_type": "token de actualización",
},
)
datos = respuesta.json()
si "error" en datos
elevar ValueError(f"Error al actualizar el token: {data['error']} - {data.get('error_description')}")
return datos["token_de_acceso"]// Actualiza un token de acceso de OAuth de Google - Node.js (fetch)
async function refrescarTokenAccesoGoogle(actualizarToken) {
const parámetros = new URLSearchParams({
client_id: "TU_ID_DE_CLIENTE",
client_secret: "TU_CLIENT_SECRET",
refresh_token: refreshToken,
tipo_otorgamiento: "token de actualización",
});
const res = await fetch("https://oauth2.googleapis.com/token", {
method: "PUBLICAR",
cabeceras: { "Tipo-Contenido": "application/x-www-form-urlencoded" },
body: params.toString(),
});
const datos = await res.json();
si (datos.error) lanzar nuevo Error(`${data.error}: ${data.error_description}`);
return data.token_acceso; // válido por 3600s
}Probar interactivamente: Utilice la Google OAuth Playground para probar el flujo de tokens de actualización sin escribir código. Te permite obtener tokens, inspeccionar respuestas y depurar el ciclo de vida completo del token de actualización de Google OAuth2 en una interfaz de usuario de navegador.
invalid_grant: guía rápida
Cuando un token de actualización de Google OAuth ha expirado, ha sido revocado o es inválido, el endpoint del token devuelve un concesión_inválida error. Esta es la señal canónica de que tu token de actualización de Google OAuth ya no es utilizable. Aquí están las causas más comunes y sus soluciones inmediatas.
La aplicación está en estado "Testing". El token expiró después de 7 días. Solución: publicar la aplicación o cambiar a Workspace interno.
Token no utilizado durante 6 meses. Solución: implementar actualización de mantenimiento (keep-alive); programar intercambio mensual de tokens.
El usuario consintió demasiadas veces; el token más antiguo fue revocado silenciosamente. Solución: almacene los tokens en el servidor, nunca vuelva a solicitar innecesariamente.
El usuario eliminó tu aplicación de la configuración de Cuentas de Google. Corrección: eliminar el token almacenado; mostrar al usuario un aviso de reautorización.
El usuario cambió la contraseña de Google mientras su aplicación tiene ámbitos de Gmail sensibles. Solución: capturar el error, solicitar la reautorización.
Credenciales de client_id/secret no coinciden, o el token fue emitido por una aplicación diferente. Solución: verifique las credenciales; pruebe con OAuth Playground.
Para un desglose completo de cada código de error de Google OAuth con estado HTTP, tabla de causas y soluciones a nivel de código, consulta el completo Guía de referencia de errores de Google OAuth.
Tokens de actualización administrados con Unipile
Crear y mantener un ciclo de vida robusto de los tokens de actualización de Google OAuth es un trabajo de ingeniería nada trivial. Unipile actúa como intermediario técnico independiente en nombre de cada usuario autenticado, manejando el almacenamiento de tokens, la programación de actualizaciones y la recuperación de errores en el lado del servidor, para que su equipo entregue funciones en lugar de depurar concesión_inválida a las 2 de la madrugada.
Unipile almacena los tokens de actualización de tus usuarios cifrados en el servidor y actualiza proactivamente los tokens de acceso antes de que expiren. Ningún error 401 llega a tu aplicación.
La propia aplicación OAuth de Unipile ha superado la evaluación de seguridad CASA Nivel 2. Durante su POC, sus usuarios autorizan a través del flujo verificado de Unipile; no se aplica ningún límite de prueba de 7 días.
Cuando tu propia verificación de Google OAuth sea aprobada, cambia al modo BYOC: tus usuarios se autorizan a través de tu propia aplicación de Google verificada, mientras que Unipile continúa manejando la infraestructura de actualización de tokens.
Unipile proporciona un solo API de Gmail capa de abstracción que también cubre Outlook (Microsoft 365 + Exchange Online) e IMAP, cada uno con su propio ciclo de vida de tokens administrado, para que nunca implemente lógica de actualización específica del proveedor.
POC con clave Unipile: Conecta a tus primeros usuarios autenticados de inmediato a través del flujo CASA Nivel 2 de Unipile. Sin caducidad de 7 días. Acceso completo a la API de Gmail a través del endpoint unificado de Unipile.
Certificar en paralelo: Inicia tu propia aplicación de Google para la verificación de OAuth mientras ejecutas tu integración en producción. Unipile admite esta vía paralela.
Cambiar a BYOC: Una vez que Google apruebe tu aplicación, activa el modo Bring-Your-Own-Credentials. La vida útil de tu token de actualización de Google OAuth será indefinida en producción. Unipile continuará gestionando la infraestructura de actualización.
#: Obtener la lista de correos electrónicos a través de Unipile — el token de actualización se gestiona en el servidor
import solicita
encabezados = {
"Clave API X": "TU_CLAVE_API_DE_UNIPILE",
"aceptar": "application/json",
}
# account_id = ID de la cuenta vinculada del usuario autenticado
response = requests.get(
"https://api7.unipile.com:13046/api/v1/emails",
params={"account_id": "acc_XXXXXXXX"},
cabeceras=cabeceras,
)
El token de actualización de Google OAuth # se actualiza automáticamente mediante Unipile
correos = respuesta.json()["artículos"]Google OAuth Token de actualización - Preguntas frecuentes
Preguntas frecuentes sobre la expiración del token de actualización de Google OAuth, la vida útil y el ciclo de vida del token de actualización de Google OAuth2.
Sí, bajo 6 condiciones específicas. La más común es la Límite de prueba de 7 díasSi tu app está en estado "En prueba" en la consola de Google Cloud, todos los tokens de actualización caducan después de 7 días. En producción con una app verificada, los tokens son efectivamente permanentes a menos que: (1) no se utilicen durante 6 meses, (2) el usuario revoque el acceso, (3) se cambie la contraseña con ámbitos de Gmail, (4) se supere el límite de 50 tokens, o (5) la app pierda la verificación para ámbitos sensibles. Entender Verificación de Google OAuth es clave para evitar vencimientos inesperados.
Duración del token de actualización de Google OAuth depende del estado de tu aplicación. En modo de prueba: 7 días máximo, independientemente del uso. En producción (aplicación verificada): sin fecha de caducidad fija - los tokens duran indefinidamente siempre que se utilicen al menos una vez cada 6 meses, no se supere el límite de 50 tokens y el usuario no haya revocado el acceso. Las aplicaciones internas de Google Workspace tampoco tienen un límite de 7 días.
En Google OAuth token de actualización caducidad de 7 días se aplica cuando el estado de tu pantalla de consentimiento de OAuth es "En pruebas" en la Google Cloud Console. Google impone este límite en todas las aplicaciones no verificadas como medida de seguridad. También coincide con el 100 usuarios de prueba límite. La solución es publicar tu aplicación y completar la verificación de Google OAuth (para producción) o configurar la aplicación en "Interno" si es solo para Workspace.
Para prevenir el token de actualización de Google OAuth2 vencimiento debido a 6 meses de inactividad: programar una publicacion mensual para https://oauth2.googleapis.com/token con grant_type=refresh_token. Esto reinicia el reloj de inactividad. Ten en cuenta que realizar llamadas a la API de Gmail con el token de acceso existente NO cuenta como "uso" del token de actualización; solo el punto de conexión de intercambio de tokens reinicia el temporizador. Almacena los tokens en el lado del servidor y nunca vuelvas a solicitar a los usuarios innecesariamente para mantenerte por debajo del límite de 50 tokens.
concesión_inválida significa tu caducidad del token de actualización de Google OAuth se ha activado o el token es inválido. Causas principales: el token ha expirado (límite de prueba de 7 días o inactividad de 6 meses), el usuario revocó el acceso desde la configuración de la Cuenta de Google, se superó el límite de 50 tokens por cliente-usuario y este token fue desplazado, cambio de contraseña con ámbitos de Gmail o credenciales de cliente no coincidentes. Vea la información completa. Guía de errores de Google OAuth para pasos de remediación detallados por causa.
No puedes obtener un nuevo token de actualización de Google OAuth sin la interacción del usuario, por diseño. Los tokens de actualización solo se emiten durante el flujo de autorización de consentimiento del usuario. Si tu token ha expirado o ha sido revocado, debes redirigir al usuario nuevamente a través del flujo de OAuth. Añadir consentimiento fuerza una nueva pantalla de consentimiento y emite un nuevo token, pero cuenta contra el límite de 50 tokens. La mejor práctica es evitar la expiración en primer lugar: almacene los tokens de forma segura, implemente actualizaciones de "keep-alive" y gestione concesión_inválida maneja los errores con elegancia solicitando la re-autorización solo cuando sea necesario.
PUBLICAR a https://oauth2.googleapis.com/token con Content-Type: application/x-www-form-urlencoded y parámetros de cuerpo: client_id, secreto_cliente, token de actualizacióny grant_type=refresh_token. La respuesta devuelve un nuevo token_de_acceso válido por 3,600 segundos. Si la respuesta contiene "error": "concesión_inválida", la token de actualización de la API de Google ya no es válida y se requiere la reautorización del usuario. Consulte los ejemplos de código en la sección 5 para las implementaciones de curl, Python y Node.js.
¿Aún tienes preguntas sobre los tokens de actualización de Google OAuth? Nuestro equipo está aquí para ayudarte.
ES 
EN 
FR 
DE 
IT 
BR 
NL 
PL 
TR