Le long lived access token Facebook et son horloge de 60 jours

Qu'est-ce qu'un long lived access token Facebook ?

Meta émet un long lived access token Facebook en échange d'un jeton de courte durée, et sa documentation fixe la vie de ce jeton à environ 60 jours. L'échange est un unique appel côté serveur. La raison de son existence est énoncée dès la première ligne du guide 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 trace la distinction en une phrase dans son aperçu des access tokens : « 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 phrase qui suit est celle que la plupart des intégrations ignorent. Meta écrit qu'il ne faut pas compter sur la stabilité de ces durées de vie, parce qu'« they may change without warning or expire early ».

Comment échanger un jeton de courte durée contre un jeton de longue durée ?

Vous interrogez l'endpoint GET oauth/access_token avec grant_type=fb_exchange_token. L'exemple 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}"

Quatre entrées, dont trois vous appartiennent. client_id est l'App ID, client_secret est l'App Secret, et fb_exchange_token est le User access token de courte durée que vous détenez déjà. La réponse :

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

Meta annote expires_in dans l'exemple lui-même comme « The number of seconds until the token expires. » Ce nombre mérite un calcul. Soixante jours font 5 184 000 secondes. La valeur documentée par Meta est 5 183 944, soit 56 secondes de moins que 60 jours ronds. L'écart est négligeable en pratique et instructif sur le principe : le chiffre documenté n'est pas une promesse de 60 jours exacts, c'est une valeur d'exemple, et Meta dit que la durée de vie sous-jacente peut changer.

Trois réserves accompagnent l'échange, dans les termes de Meta :

• « You can not use an expired token to request a long-lived token. » Une fois le jeton de courte durée mort, l'utilisateur doit repasser par la connexion.
• « 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 deuxième réserve porte aussi une consigne de stockage que l'on saute souvent : le jeton de longue durée « will be a different string than the original token, so if you're storing these tokens, replace the old one. »

Courte durée contre longue durée, en un tableau

Le mobile est l'exception qui perd les gens qui lisent des articles sur les intégrations web. Meta écrit 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. » Le rafraîchissement quotidien n'a lieu que si la personne continue d'utiliser l'application, puisqu'« If no requests are made, the token will expire after about 60 days. »

Pourquoi un Page access token se comporte-t-il différemment ?

Un Page access token dérivé d'un User access token de longue durée n'expire pas. Meta l'énonce simplement : « Long-lived Page access token do not have an expiration date and only expire or are invalidated under certain conditions. »

Vous en obtenez un en appelant l'edge accounts avec le User token de longue durée :

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

La réponse renvoie un objet par Page, chacun portant son propre access_token, plus category, name, id et un tableau tasks contenant des valeurs comme ANALYZE, ADVERTISE, MODERATE, CREATE_CONTENT et MANAGE. Il n'y a aucun expires_in dans cette charge utile, ce qui est la version côté réponse de la même affirmation.

Deux conditions l'encadrent. Meta exige que « The person requesting the token must have a role on the Page », et note ailleurs que « Page access tokens are unique to each Page, admin, and app combination. » Changez l'un de ces trois éléments et vous avez un autre jeton, donc un jeton de Page ne survit pas à la perte de rôle de l'admin qui l'a créé.

C'est la principale raison structurelle pour laquelle les intégrations de publication sont bâties sur des jetons de Page plutôt que sur des jetons d'utilisateur. Une file qui doit survivre à une horloge de 60 jours a besoin d'une stratégie de rafraîchissement ; une file sur un jeton de Page n'a aucune horloge à laquelle survivre. C'est aussi pourquoi connecter un compte Instagram à une Page professionnelle Facebook compte pour le travail d'API et pas seulement pour la publication croisée, puisque l'Instagram API with Facebook Login s'authentifie avec un Facebook Page access token.

Qu'est-ce qui invalide un jeton avant 60 jours ?

Meta ne publie jamais de liste complète. La page sur les jetons de longue durée dit que les jetons de Page « only expire or are invalidated under certain conditions » et renvoie vers sa page de débogage pour ces conditions. Cette page nomme une cause générale et montre trois réponses d'erreur précises, et elle n'énumère jamais les conditions sous forme de liste.

La cause générale, citée : « Due to security related events, access tokens may be invalidated before the expected expiration time. »

Les trois échecs documentés, renvoyant chacun le code 190 :

Le changement de mot de passe est celui qui prend les équipes de court, parce qu'il invalide des jetons sans aucune faute de l'intégration et ne génère aucun signal. Meta est explicite sur l'absence de ce signal : « 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. »

Cette phrase est le cœur opérationnel de tout le sujet. Il n'existe aucun webhook pour un jeton mort. Un post programmé est l'endroit où la plupart des équipes découvrent le problème, et c'est pourquoi un jeton mort figure haut dans la liste des raisons pour lesquelles les posts programmés Facebook cessent de fonctionner sans changement visible du côté de la publication.

Comment vérifier ce qu'il reste réellement à un jeton ?

Interrogez debug_token plutôt que de vous fier au chiffre de 60 jours :

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

Meta ajoute une contrainte : « The tokens must be from the same app. » La réponse renvoie app_id, type, application, expires_at, data_access_expires_at, is_valid, scopes, granular_scopes et user_id, et Meta note que « For long-lived access tokens the issued_at field is also returned. »

Deux de ces champs sont des horloges distinctes et sont confondus en permanence. expires_at indique quand le jeton cesse de fonctionner. data_access_expires_at est une autre échéance qui régit l'accès continu aux données de l'utilisateur. Un jeton peut être valide face au premier et restreint par le second.

Intégrez la vérification au pipeline, pas à un manuel d'exploitation. Lire expires_at avant une publication coûte une requête et transforme un échec silencieux en une réautorisation programmée, de la même façon que lire le content_publishing_limit d'Instagram avant de publier transforme une limite de fréquence en décision de file d'attente. Les deux sont des lectures bon marché qui remplacent une erreur imprévisible par un nombre prévisible.

Une classe d'applications échappe entièrement à l'horloge. Meta écrit qu'« 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 », et étend cela aux jetons de System User dans Business Manager. Le temps cesse d'être le mode de défaillance ; les invalidations liées aux événements de sécurité, non.

Questions fréquentes

Combien de temps dure un long lived access token Facebook ?

Environ 60 jours. La réponse d'exemple de Meta renvoie expires_in: 5183944 secondes, soit 56 secondes de moins que 60 jours, et Meta prévient que la durée de vie « may change without warning ».

Quel est l'endpoint d'échange exact ?

GET https://graph.facebook.com/{graph-api-version}/oauth/access_token avec grant_type=fb_exchange_token, client_id, client_secret et fb_exchange_token. Il doit tourner côté serveur parce qu'il porte l'app secret.

Peut-on rafraîchir un jeton de longue durée avant qu'il n'expire ?

Meta ne documente l'échange que de courte durée vers longue durée, et énonce que « You can not use an expired token to request a long-lived token. » Il ne documente aucun rafraîchissement d'un User token déjà de longue durée sur le web.

Les Page access tokens expirent-ils un jour ?

Meta dit que les jetons de Page générés à partir d'un User access token de longue durée « do not have an expiration date and only expire or are invalidated under certain conditions », et il ne publie jamais ces conditions sous forme de liste complète.

Facebook vous préviendra-t-il de la mort d'un jeton ?

Non. La documentation de Meta énonce directement que « Facebook will not notify you that an access token has become invalid », et que votre application peut ne l'apprendre qu'au moment où une requête échoue.

Quelle erreur signifie que l'utilisateur a changé son mot de passe ?

Le code 190, sous-code 460, avec le message « Error validating access token: The session is invalid because the user logged out. » Meta attribue cette réponse à une personne qui « logged out of your app or changed their password ».

Que se passe-t-il si votre jeton de courte durée a déjà expiré avant l'échange ?

Meta bloque l'échange net : "You can not use an expired token to request a long-lived token." Le jeton de courte durée doit encore être valide au moment de l'appel à oauth/access_token, donc si vous attendez trop longtemps après la connexion, la seule issue est de repasser par le flux de login.

Un même jeton de longue durée peut-il servir à deux clients web différents ?

La mise en garde de Meta est sans ambiguïté : "Do not use the same long-lived tokens on more than one web client." Chaque client web est censé effectuer son propre échange et conserver son propre jeton plutôt que d'en partager un entre plusieurs propriétés.

Qu'advient-il de la chaîne du jeton de courte durée après l'échange ?

Le jeton de longue durée renvoyé par Meta "will be a different string than the original token", donc tout stockage conçu pour le jeton court doit être mis à jour. L'instruction de Meta est directe : si vous stockez ces jetons, remplacez l'ancien au lieu de garder les deux.

Les jetons de la Marketing API suivent-ils la même horloge de 60 jours ?

Les applications avec un accès Standard à la Marketing API reçoivent, selon Meta, des jetons de longue durée qui n'expirent pas dans le temps, même s'ils restent exposés à une invalidation pour d'autres raisons. Meta étend la même exception aux jetons System User dans Business Manager. L'horloge des 60 jours ne s'applique plus là, les invalidations liées à des événements de sécurité si.