Rotación del refresh token

UTILIA OS rota el refresh token en cada renovación, como recomienda OAuth 2.1, y detecta cuándo alguien reutiliza uno ya rotado. Para tu código, la consecuencia es una sola regla: después de cada renovación, guarda el refresh token que acabas de recibir y olvida el anterior. Esta página explica por qué y cómo hacerlo bien, también cuando varias partes de tu aplicación renuevan a la vez.

Qué cambia en cada renovación

Cuando llamas a POST /api/oauth/token con grant_type=refresh_token, recibes un access token nuevo, de 1 hora, y un refresh token nuevo que sustituye al que enviaste. Así vive cada refresh token:

El plazo de 90 días cuenta desde la autorización y no se alarga al rotar: si la persona autorizó el 1 de enero, la cadena caduca a principios de abril aunque hayas renovado cien veces. Después, tiene que volver a autorizar.

Por qué se rota

Si alguien roba un refresh token, sin rotación podría renovar indefinidamente sin que nadie lo notara. Con rotación, el refresh token robado y el legítimo acaban chocando: el segundo que se use ya está anulado, el servidor lo detecta y corta la cadena entera. El atacante se queda sin acceso y la persona solo tiene que volver a autorizar.

El único margen es de un minuto desde la rotación, para no confundir con un robo a dos partes de tu propia aplicación que renuevan a la vez (lo explica Renovaciones simultáneas).

Qué pasa si reutilizas uno anulado

Si llega un refresh token que se rotó hace más de un minuto, o cuya cadena ya no está viva, UTILIA OS:

• Responde 400 con error: "invalid_grant" y error_description: "Refresh token has been rotated".
• Revoca todos los tokens de esa cadena, es decir, los que nacieron de la misma autorización, incluido el access token que tuvieras en uso. Las demás autorizaciones de la misma persona con tu aplicación (otro servidor MCP, otro aparato) no se tocan.

A partir de ahí, la única salida es repetir el flujo de autorización.

Renovaciones simultáneas

Si dos procesos de tu aplicación (dos pestañas, dos trabajadores) renuevan con el mismo refresh token, el resultado depende de cuándo llega el segundo:

Si las dos peticiones se cruzan en el servidor en el mismo instante, UTILIA OS la reintenta por dentro y el segundo proceso recibe también su propio par: tu código no ve ningún error.

El margen salva las renovaciones simultáneas, no el desorden: un proceso que se queda con el refresh viejo y renueva con él más tarde corta la cadena de todos. Por eso:

• Serializa las renovaciones. En el navegador, usa navigator.locks.request o comparte una única promesa de renovación entre pestañas; en el servidor, un cerrojo por persona y cliente. Los SDK oficiales ya comparten una sola renovación cuando varias peticiones la necesitan a la vez.
• Lee el almacenamiento justo antes de renovar. Si otro proceso ya renovó mientras esperabas el cerrojo, su access token sigue vigente: úsalo y no renueves.

Cómo adaptar tu código

1. Guarda los dos tokens tras cada renovación

async function refreshTokens(storedRefreshToken, clientId) {
  const response = await fetch("https://os.utilia.ai/api/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "refresh_token",
      refresh_token: storedRefreshToken,
      client_id: clientId,
    }),
  });
 
  const body = await response.json();
  if (!response.ok) {
    throw Object.assign(new Error(body.error_description), { code: body.error });
  }
 
  // Sustituye los DOS tokens en tu almacenamiento persistente.
  await tokenStore.save({
    accessToken: body.access_token,
    refreshToken: body.refresh_token,
    expiresAt: Date.now() + body.expires_in * 1000,
  });
 
  return body;
}

tokenStore y token_store representan tu propio almacenamiento (base de datos, sesión, archivo).

2. Renueva una sola vez y trata invalid_grant

async function getFreshAccessToken(clientId) {
  // withRefreshLock: tu cerrojo por persona y cliente (navigator.locks en el
  // navegador, un cerrojo en tu base de datos o en Redis en el servidor).
  return withRefreshLock(async () => {
    const stored = await tokenStore.read();
    // Otro proceso pudo renovar mientras esperabas el cerrojo.
    if (stored.expiresAt - Date.now() > 60_000) return stored.accessToken;
 
    try {
      const tokens = await refreshTokens(stored.refreshToken, clientId);
      return tokens.access_token;
    } catch (err) {
      if (err.code !== "invalid_grant") throw err;
      // Reutilización fuera de plazo, caducidad, persona inactiva o sin alcance:
      // volver a autorizar.
      await tokenStore.clear();
      throw new Error("REAUTHORIZE");
    }
  });
}

withRefreshLock y _refresh_lock representan tu cerrojo; tokenStore y token_store, tu almacenamiento, los mismos del paso anterior.

Preguntas frecuentes

¿Puedo seguir usando un refresh token antiguo si lo guardé en varios sitios? No. Solo vale el último. Uno anterior solo sirve en el minuto siguiente a su rotación; después, revoca la cadena.

¿Cuánto vive la cadena? 90 días desde la autorización. Rotar no alarga ese plazo.

¿Y si mi aplicación está mucho tiempo sin conexión? Si al volver el refresh token ha caducado, la renovación responde invalid_grant (Refresh token has expired). Detéctalo y lanza de nuevo la autorización.

¿Al renovar puedo cambiar de servidor MCP? No. El token renovado sigue atado al mismo servidor. Para otro servidor, pide otra autorización con su resource.

Relación con otros mecanismos