Ciclo de vida del token en la práctica

Todas las guías de flujo OAuth mencionan refresh_token, pero una integración de larga duración (una que sigue funcionando a lo largo de muchas solicitudes, workers o días) necesita más que “sustituir el token cuando expire”. Esta página cubre las duraciones reales de los tokens, cómo almacenar en caché un token entre varios workers, cuándo renovarlo y qué puede invalidar un token antes de que expire por sí solo.

---

Duración de los tokens por flujo

La duración del token de acceso es una única duración fija, igual para todos los flujos. La del token de actualización no lo es: depende de qué flujo OAuth lo emitió.

Flujo	TTL del token de acceso	TTL del token de actualización
Flujo de Client Credentials	Alrededor de 1 hora	Alrededor de 30 días
Flujo de aplicación nativa (PKCE, redirección loopback)	Alrededor de 1 hora	Sin expiración fija: permanece válido hasta que se sustituye por rotación o se revoca
Flujo de Authorization Code + redireccionamiento personalizado	Alrededor de 1 hora	Sin expiración fija: permanece válido hasta que se sustituye por rotación o se revoca

Nota

Ambos flujos de Authorization Code emiten un token de actualización sin ningún reloj de sesión. Aun así, no queda sin usarse indefinidamente: es un token de un solo uso que se sustituye en cada renovación (consulta Condiciones de carrera en renovaciones concurrentes más abajo), y deja de funcionar de inmediato si se revoca la concesión.

Almacena el token en caché, no generes uno por solicitud

Solicitar un token de acceso nuevo en cada llamada a la API, o de forma independiente en cada proceso worker, funciona, pero desperdicia un viaje de ida y vuelta en cada solicitud para un token que ya es válido durante alrededor de una hora. Solicita un token, guárdalo en caché (en memoria para un solo proceso, o en un almacén compartido como Redis para una flota de workers) según la credencial que lo emitió, y entrega el token en caché a cada solicitud hasta que esté cerca de expirar.

Esto también importa para el token de actualización: cuantos menos procesos lo intercambien de forma independiente, menos probable es que te encuentres con la condición de carrera descrita más abajo.

Renueva al expirar, no solo ante un 401

Como la TTL del token de acceso es fija y se conoce de antemano, renueva de forma proactiva: registra cuándo obtuviste el token (o decodifica su claim exp) y solicita uno nuevo poco antes de ese momento, en lugar de esperar a que una solicitud falle primero.

Aun así, maneja una solicitud fallida como respaldo, pero distingue según el error recibido:

• 401 con not_authenticated: la solicitud no llevaba ningún token portador utilizable. Es un error del lado del cliente (encabezado Authorization ausente o mal formado), no una señal para renovar.
• 401 con invalid_token: falló la verificación de firma o de expiración del token. Renueva y reintenta una vez.
• 403: nunca es un problema de token. El token es válido; quien llama no tiene el scope, el acceso al contenido o el rol que la operación requiere. Renovar no ayudará. Consulta Códigos de error: Límite de tasa, autenticación y control de acceso para el detalle completo de cada código.

Condiciones de carrera en renovaciones concurrentes

Un token de actualización es de un solo uso: al intercambiarlo con grant_type=refresh_token se invalida ese token de actualización y se emiten juntos un nuevo token de acceso y un nuevo token de actualización. Si varios workers comparten un token de actualización en caché y dos de ellos intentan renovarlo casi al mismo tiempo, solo uno de los intercambios tiene éxito; el otro recibe un 401 genérico, no un error distinguible de “ya usado”.

Precaución

No dejes que cada worker renueve de forma independiente contra un token de actualización compartido. Designa un único responsable para la llamada de renovación (un bloqueo alrededor de la ruta de renovación, o una rutina dedicada) y haz que el resto de los workers lean el token de acceso resultante desde la caché compartida en lugar de renovarlo ellos mismos.

Qué invalida un token antes de tiempo

Ninguno de los eventos siguientes revoca directamente un token de acceso vigente. Cada uno solo bloquea algo nuevo (una nueva solicitud de token, o la próxima renovación) mientras el token de acceso que ya tienes sigue funcionando hasta que se agota su propia TTL.

Desencadenante	Efecto
Se rota el secreto de cliente de la aplicación OAuth	Las nuevas solicitudes de token o renovación con el secreto anterior se rechazan de inmediato. Un token de acceso ya emitido no se ve afectado y sigue funcionando hasta que expira de forma natural.
Se elimina la aplicación OAuth o su usuario de servicio	Bloquea la emisión de nuevos tokens para esa aplicación. Los tokens ya emitidos no se revocan de forma proactiva.
Se cambian los scopes de la aplicación OAuth	Un token de acceso ya emitido conserva sus scopes originales durante el resto de su vigencia. El token solo adopta los nuevos scopes la próxima vez que se renueva o se reemite.
Se revoca explícitamente la concesión	Bloquea de inmediato el próximo intento de renovación. El token de acceso aún válido no se fuerza a expirar y sigue funcionando hasta que expira de forma natural.

Nota

La ventana de exposición práctica tras cualquiera de estos eventos es la propia TTL del token de acceso (alrededor de una hora), no la del token de actualización, ya que ninguno de ellos afecta a un token ya emitido. Para reducir esa ventana a cero de inmediato, revoca la concesión y rota el secreto a la vez, y luego trata la integración como no autorizada hasta que haya transcurrido una TTL de token de acceso.

¿Qué sigue?

• Códigos de error para el detalle completo de las respuestas 401 y 403
• Flujo de Client Credentials, Flujo de aplicación nativa o Flujo de Authorization Code + redireccionamiento personalizado para obtener tu primer token