El token de acceso de larga duración de Facebook y su reloj de 60 días

¿Qué es un token de acceso de larga duración de Facebook?

Meta emite un token de acceso de larga duración de Facebook a cambio de uno de corta duración, y su documentación sitúa la vida de ese token en unos 60 días. El intercambio es una sola llamada del lado del servidor. La razón de que exista está en la primera línea de la guía de Meta: "Default User and Page access tokens are short-lived, expiring in hours, however, you can exchange a short-lived token for a long-lived token".

Meta traza la distinción en una frase de su resumen sobre tokens de acceso: "Access tokens come in two forms: short-lived and long-lived. Short-lived tokens typically last about one to two hours, while long-lived tokens last about 60 days".

La frase que viene después es la que casi todas las integraciones ignoran. Meta escribe que no deberías depender de que esas duraciones sigan siendo las mismas, porque "they may change without warning or expire early".

¿Cómo se cambia un token de corta duración por uno de larga duración?

Consultas el endpoint GET oauth/access_token con grant_type=fb_exchange_token. El propio ejemplo de curl de Meta:

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/access_token?
    grant_type=fb_exchange_token&
    client_id={app-id}&
    client_secret={app-secret}&
    fb_exchange_token={your-access-token}"

Cuatro entradas, tres de las cuales son tuyas. client_id es el App ID, client_secret es el App Secret y fb_exchange_token es el token de acceso de usuario de corta duración que ya tienes. La respuesta:

{
  "access_token": "{long-lived-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944
}

Meta anota expires_in en el propio ejemplo como "The number of seconds until the token expires". Merece la pena hacer la aritmética de ese número. Sesenta días son 5.184.000 segundos. El valor documentado de Meta es 5.183.944, que se queda 56 segundos por debajo de unos 60 días redondos. La diferencia es trivial en la práctica e instructiva en el principio: la cifra documentada no es una promesa de exactamente 60 días, es un valor de ejemplo, y Meta dice que la duración de fondo puede cambiar.

Tres salvedades acompañan al intercambio, en palabras de Meta:

• "You can not use an expired token to request a long-lived token." Una vez que el token de corta duración está muerto, el usuario tiene que volver a pasar por el inicio de sesión.
• "Make this call from your server, not a client. Your app secret is included in this API call, so you should never make the request client-side."
• "Do not use the same long-lived tokens on more than one web client."

La segunda salvedad lleva además una instrucción de almacenamiento que se suele saltar: el token de larga duración "will be a different string than the original token, so if you're storing these tokens, replace the old one".

Corta duración frente a larga duración, en una tabla

El móvil es la excepción que confunde a quien lee sobre integraciones web. Meta escribe que "Native mobile apps using Facebook's SDKs get long-lived User access tokens, good for about 60 days. These tokens are refreshed once per day, when the person using your app makes a request to Facebook's servers". Esa renovación diaria solo ocurre si la persona sigue usando la app, ya que "If no requests are made, the token will expire after about 60 days".

¿Por qué se comporta distinto un token de acceso de página?

Un token de acceso de página derivado de un token de acceso de usuario de larga duración no caduca. Meta lo dice con claridad: "Long-lived Page access token do not have an expiration date and only expire or are invalidated under certain conditions".

Consigues uno llamando al edge de accounts con el token de usuario de larga duración:

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/{app-scoped-user-id}/accounts?
  access_token={long-lived-user-access-token}"

La respuesta devuelve un objeto por página, cada uno con su propio access_token, más category, name, id y un array tasks con valores como ANALYZE, ADVERTISE, MODERATE, CREATE_CONTENT y MANAGE. No hay ningún expires_in en esa carga, que es la versión en forma de respuesta de la misma afirmación.

Dos condiciones la limitan. Meta exige que "The person requesting the token must have a role on the Page", y señala en otro sitio que "Page access tokens are unique to each Page, admin, and app combination". Cambia cualquiera de esos tres y tienes un token distinto, así que un token de página no sobrevive a que el admin que lo creó pierda su rol.

Esta es la mayor razón estructural de que las integraciones de publicación se construyan sobre tokens de página en lugar de sobre tokens de usuario. Una cola que tiene que sobrevivir a un reloj de 60 días necesita una estrategia de renovación; una cola sobre un token de página no tiene reloj al que sobrevivir. Es también por lo que conectar una cuenta de Instagram a una página de empresa de Facebook importa para el trabajo de API y no solo para publicar en dos sitios, ya que Instagram API with Facebook Login se autentica con un token de acceso de página de Facebook.

¿Qué invalida un token antes de los 60 días?

Meta nunca publica una lista completa. La página del token de larga duración dice que los tokens de página "only expire or are invalidated under certain conditions" y enlaza a su página de depuración para esas condiciones. Esa página nombra una causa general y muestra tres respuestas de error concretas, y nunca enumera las condiciones como lista.

La causa general, citada: "Due to security related events, access tokens may be invalidated before the expected expiration time".

Los tres fallos documentados, cada uno devolviendo el código 190:

Un cambio de contraseña es el que pilla desprevenidos a los equipos, porque invalida tokens sin culpa alguna de la integración y no genera ninguna señal. Meta es explícita sobre la ausencia de esa señal: "Facebook will not notify you that an access token has become invalid. Unless you have sent the expiry time to your app along with the access token, your app may only learn that a given token has become invalid when you attempt to make a request to the API".

Esa frase es el corazón operativo de todo el asunto. No hay webhook para un token muerto. Una publicación programada es donde la mayoría de los equipos descubren el problema, y por eso un token muerto está arriba en la lista de razones por las que las publicaciones programadas de Facebook dejan de funcionar sin ningún cambio evidente en el lado de la publicación.

¿Cómo compruebas lo que le queda de verdad a un token?

Consulta debug_token en vez de fiarte de la cifra de 60 días:

curl -i -X GET "https://graph.facebook.com/debug_token?
  input_token={input-token}&
  access_token={valid-access-token}"

Meta añade una restricción: "The tokens must be from the same app". La respuesta devuelve app_id, type, application, expires_at, data_access_expires_at, is_valid, scopes, granular_scopes y user_id, y Meta señala que "For long-lived access tokens the issued_at field is also returned".

Dos de esos campos son relojes distintos y se confunden constantemente. expires_at es cuándo el token deja de funcionar. data_access_expires_at es otro plazo que rige el acceso continuado a los datos del usuario. Un token puede ser válido frente al primero y estar restringido por el segundo.

Mete la comprobación en la canalización, no en un manual de operaciones. Leer expires_at antes de publicar cuesta una petición y convierte un fallo silencioso en una reautorización programada, igual que leer el content_publishing_limit de Instagram antes de publicar convierte un límite de tasa en una decisión de cola. Las dos son lecturas baratas que sustituyen un error que no puedes predecir por un número que sí.

Una clase de app escapa del reloj por completo. Meta escribe que "Apps with Standard access to the Marketing API receive long-lived tokens that do not expire based on time, though they are still subject to invalidation for other reasons", y lo extiende a los tokens de usuario de sistema en Business Manager. El tiempo deja de ser el modo de fallo; las invalidaciones por eventos de seguridad no.

Preguntas frecuentes

¿Cuánto dura un token de acceso de larga duración de Facebook?

Unos 60 días. La respuesta de ejemplo de Meta devuelve expires_in: 5183944 segundos, que son 56 segundos menos de 60 días, y Meta advierte de que la duración "may change without warning".

¿Cuál es el endpoint exacto del intercambio?

GET https://graph.facebook.com/{graph-api-version}/oauth/access_token con grant_type=fb_exchange_token, client_id, client_secret y fb_exchange_token. Tiene que correr del lado del servidor porque lleva el app secret.

¿Se puede renovar un token de larga duración antes de que caduque?

Meta documenta el intercambio solo de corta a larga duración, y afirma que "You can not use an expired token to request a long-lived token". No documenta ninguna renovación de un token de usuario que ya sea de larga duración en la web.

¿Los tokens de acceso de página caducan alguna vez?

Meta dice que los tokens de página generados a partir de un token de acceso de usuario de larga duración "do not have an expiration date and only expire or are invalidated under certain conditions", y nunca publica esas condiciones como lista completa.

¿Facebook te avisará cuando un token muera?

No. La documentación de Meta afirma directamente que "Facebook will not notify you that an access token has become invalid", y que tu app puede enterarse solo cuando una petición falle.

¿Qué error significa que el usuario cambió su contraseña?

El código 190, subcódigo 460, con el mensaje "Error validating access token: The session is invalid because the user logged out". Meta atribuye esa respuesta a una persona que "logged out of your app or changed their password".

¿Qué pasa si tu token de corta duración ya caducó antes de intercambiarlo?

Meta bloquea el intercambio de plano: "You can not use an expired token to request a long-lived token." El token de corta duración tiene que seguir vivo cuando llamas a oauth/access_token, así que si esperas demasiado tras el login, la única salida es pasar otra vez por el flujo de inicio de sesión.

¿Puede un mismo token de larga duración servir a dos clientes web distintos?

La advertencia de Meta es clara: "Do not use the same long-lived tokens on more than one web client." Cada cliente web está pensado para hacer su propio intercambio y guardar su propio token en lugar de compartir uno entre varias propiedades.

¿Qué pasa con la cadena del token de corta duración después del intercambio?

El token de larga duración que devuelve Meta "will be a different string than the original token", así que cualquier almacenamiento pensado para el token corto necesita actualizarse. La instrucción de Meta es directa: si guardas estos tokens, reemplaza el anterior en vez de conservar los dos.

¿Los tokens de la Marketing API siguen el mismo reloj de 60 días?

Las apps con acceso Standard a la Marketing API reciben, según Meta, tokens de larga duración que no caducan por tiempo, aunque siguen expuestos a invalidación por otros motivos. Meta extiende la misma excepción a los tokens de System User en Business Manager. Ahí el reloj de 60 días deja de aplicar, pero las invalidaciones por eventos de seguridad siguen vigentes.