Das Facebook Long Lived Access Token und seine 60-Tage-Uhr

Was ist ein Facebook Long Lived Access Token?

Meta gibt ein Facebook Long Lived Access Token im Tausch gegen ein kurzlebiges aus, und seine Dokumentation setzt die Lebensdauer dieses Tokens bei etwa 60 Tagen an. Der Tausch ist ein einzelner serverseitiger Aufruf. Der Grund für seine Existenz steht in der ersten Zeile von Metas Leitfaden: „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 zieht die Unterscheidung in einem Satz in seiner Übersicht zu 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.“

Der Satz danach ist der, den die meisten Integrationen überlesen. Meta schreibt, Sie sollten sich nicht darauf verlassen, dass diese Lebensdauern gleich bleiben, weil „they may change without warning or expire early“.

Wie tauschen Sie ein kurzlebiges Token gegen ein langlebiges?

Sie fragen den Endpunkt GET oauth/access_token mit grant_type=fb_exchange_token ab. Metas eigenes curl-Beispiel:

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}"

Vier Eingaben, drei davon gehören Ihnen. client_id ist die App-ID, client_secret ist das App-Secret, und fb_exchange_token ist das kurzlebige User Access Token, das Sie schon haben. Die Antwort:

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

Meta kommentiert expires_in im Beispiel selbst als „The number of seconds until the token expires“. Diese Zahl lohnt eine Rechnung. Sechzig Tage sind 5.184.000 Sekunden. Metas dokumentierter Wert ist 5.183.944, was 56 Sekunden unter runden 60 Tagen liegt. Die Lücke ist praktisch bedeutungslos und im Prinzip lehrreich: Die dokumentierte Zahl ist kein Versprechen von genau 60 Tagen, sie ist ein Beispielwert, und Meta sagt, die zugrunde liegende Lebensdauer kann sich ändern.

Drei Vorbehalte hängen am Tausch, in Metas Worten:

• „You can not use an expired token to request a long-lived token.“ Ist das kurzlebige Token tot, muss der Nutzer erneut durch den Login.
• „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.“

Der zweite Vorbehalt trägt außerdem eine Speicheranweisung, die übersprungen wird: Das langlebige Token „will be a different string than the original token, so if you're storing these tokens, replace the old one“.

Kurzlebig gegen langlebig, in einer Tabelle

Mobil ist die Ausnahme, die alle verwirrt, die über Web-Integrationen lesen. Meta schreibt, dass „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.“ Die tägliche Erneuerung passiert nur, wenn die Person die App weiter nutzt, denn „If no requests are made, the token will expire after about 60 days“.

Warum verhält sich ein Page Access Token anders?

Ein Page Access Token, das aus einem langlebigen User Access Token abgeleitet ist, hat kein Ablaufdatum. Meta sagt es klar: „Long-lived Page access token do not have an expiration date and only expire or are invalidated under certain conditions.“

Sie bekommen eines, indem Sie die accounts-Kante mit dem langlebigen User Token aufrufen:

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

Die Antwort liefert ein Objekt pro Seite, jedes mit eigenem access_token, plus category, name, id und einem tasks-Array mit Werten wie ANALYZE, ADVERTISE, MODERATE, CREATE_CONTENT und MANAGE. In dieser Nutzlast gibt es kein expires_in, was die Antwortform derselben Aussage ist.

Zwei Bedingungen begrenzen das. Meta verlangt, dass „The person requesting the token must have a role on the Page“, und merkt an anderer Stelle an, dass „Page access tokens are unique to each Page, admin, and app combination“. Ändern Sie eines dieser drei Dinge, und Sie haben ein anderes Token, ein Seiten-Token überlebt also nicht, dass der Admin, der es erstellt hat, seine Rolle verliert.

Das ist der größte strukturelle Grund dafür, dass Veröffentlichungsintegrationen auf Seiten-Tokens statt auf User-Tokens gebaut werden. Eine Warteschlange, die eine 60-Tage-Uhr überleben muss, braucht eine Erneuerungsstrategie; eine Warteschlange auf einem Seiten-Token hat keine Uhr zu überleben. Es ist auch der Grund, warum ein Instagram-Konto mit einer Facebook-Unternehmensseite zu verbinden für API-Arbeit zählt und nicht nur für Cross-Posting, da die Instagram API mit Facebook Login sich mit einem Facebook Page Access Token authentifiziert.

Was macht ein Token vor 60 Tagen ungültig?

Meta veröffentlicht nie eine vollständige Liste. Die Seite zum langlebigen Token sagt, Seiten-Tokens „only expire or are invalidated under certain conditions“, und verlinkt für diese Bedingungen auf die Debugging-Seite. Diese Seite nennt eine allgemeine Ursache und zeigt drei konkrete Fehlerantworten, und sie zählt die Bedingungen nie als Liste auf.

Die allgemeine Ursache, zitiert: „Due to security related events, access tokens may be invalidated before the expected expiration time.“

Die drei dokumentierten Fehlschläge, jeder mit Code 190:

Eine Passwortänderung ist die, die Teams unvorbereitet trifft, denn sie macht Tokens ohne Verschulden der Integration ungültig und erzeugt kein Signal. Meta ist beim Fehlen dieses Signals ausdrücklich: „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.“

Dieser Satz ist der operative Kern des ganzen Themas. Es gibt keinen Webhook für ein totes Token. Ein geplanter Beitrag ist der Ort, an dem die meisten Teams das Problem entdecken, weshalb ein totes Token weit oben auf der Liste der Gründe steht, warum geplante Facebook-Beiträge nicht mehr funktionieren, ohne sichtbare Änderung an der Veröffentlichungsseite.

Wie prüfen Sie, was ein Token wirklich noch übrig hat?

Fragen Sie debug_token ab, statt der Zahl von 60 Tagen zu vertrauen:

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

Meta ergänzt eine Bedingung: „The tokens must be from the same app.“ Die Antwort liefert app_id, type, application, expires_at, data_access_expires_at, is_valid, scopes, granular_scopes und user_id, und Meta merkt an, dass „For long-lived access tokens the issued_at field is also returned“.

Zwei dieser Felder sind getrennte Uhren und werden ständig verwechselt. expires_at ist, wann das Token aufhört zu funktionieren. data_access_expires_at ist eine andere Frist, die den weiteren Zugriff auf Nutzerdaten regelt. Ein Token kann gegenüber der ersten gültig und von der zweiten eingeschränkt sein.

Bauen Sie die Prüfung in die Pipeline, nicht in ein Runbook. expires_at vor einer Veröffentlichung zu lesen kostet eine Anfrage und verwandelt einen stillen Fehlschlag in eine geplante Neuautorisierung, genauso wie Instagrams content_publishing_limit vor der Veröffentlichung zu lesen ein Rate Limit in eine Warteschlangenentscheidung verwandelt. Beides sind billige Lesevorgänge, die einen unvorhersehbaren Fehler durch eine Zahl ersetzen, mit der Sie rechnen können.

Eine Klasse von Apps entkommt der Uhr vollständig. Meta schreibt, dass „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“, und erweitert das auf System-User-Tokens im Business Manager. Zeit ist dort nicht mehr der Fehlermodus; die Ungültigkeit durch Sicherheitsereignisse bleibt.

Häufig gestellte Fragen

Wie lange hält ein Facebook Long Lived Access Token?

Etwa 60 Tage. Metas Beispielantwort liefert expires_in: 5183944 Sekunden, was 56 Sekunden unter 60 Tagen liegt, und Meta warnt, die Lebensdauer „may change without warning“.

Wie lautet der exakte Tausch-Endpunkt?

GET https://graph.facebook.com/{graph-api-version}/oauth/access_token mit grant_type=fb_exchange_token, client_id, client_secret und fb_exchange_token. Er muss serverseitig laufen, weil er das App-Secret trägt.

Kann man ein langlebiges Token vor dem Ablauf erneuern?

Meta dokumentiert den Tausch nur von kurzlebig zu langlebig und hält fest, dass „You can not use an expired token to request a long-lived token“. Eine Erneuerung eines bereits langlebigen User Tokens im Web dokumentiert es nicht.

Laufen Page Access Tokens jemals ab?

Meta sagt, Seiten-Tokens, die aus einem langlebigen User Access Token erzeugt wurden, „do not have an expiration date and only expire or are invalidated under certain conditions“, und veröffentlicht diese Bedingungen nie als vollständige Liste.

Sagt Facebook Ihnen, wenn ein Token stirbt?

Nein. Metas Dokumentation hält direkt fest, dass „Facebook will not notify you that an access token has become invalid“, und dass Ihre App es möglicherweise erst erfährt, wenn eine Anfrage fehlschlägt.

Welcher Fehler bedeutet, dass der Nutzer sein Passwort geändert hat?

Code 190, Subcode 460, mit der Meldung „Error validating access token: The session is invalid because the user logged out.“ Meta führt diese Antwort auf eine Person zurück, die „logged out of your app or changed their password“.

Was passiert, wenn Ihr kurzlebiges Token schon abgelaufen ist, bevor Sie es tauschen?

Meta blockiert den Tausch komplett: "You can not use an expired token to request a long-lived token." Das kurzlebige Token muss beim Aufruf von oauth/access_token noch gültig sein. Warten Sie zu lange nach dem Login, bleibt nur der erneute Login-Flow.

Kann ein einziges langlebiges Token für zwei verschiedene Web-Clients dienen?

Metas Hinweis ist eindeutig: "Do not use the same long-lived tokens on more than one web client." Jeder Web-Client soll seinen eigenen Tausch-Aufruf durchführen und sein eigenes Token halten, statt eines über mehrere Properties zu teilen.

Was passiert mit dem kurzlebigen Token-String nach dem Tausch?

Das langlebige Token, das Meta zurückgibt, "will be a different string than the original token", also muss jede Speicherung, die für das kurzlebige Token gebaut wurde, aktualisiert werden. Metas Anweisung ist direkt: Wer diese Tokens speichert, soll das alte ersetzen statt beide zu behalten.

Unterliegen Marketing-API-Tokens der gleichen 60-Tage-Uhr?

Apps mit Standard-Zugriff auf die Marketing API erhalten laut Meta langlebige Tokens, die zeitlich nicht ablaufen, bleiben aber weiterhin anfällig für Invalidierung aus anderen Gründen. Meta weitet diese Ausnahme auf System User Tokens im Business Manager aus. Die 60-Tage-Uhr greift dort schlicht nicht, sicherheitsbedingte Invalidierungen schon.