Apps installieren, Zugriffsschlüssel generieren, aktualisieren und widerrufen

Ein Systemnutzer steht für Serveraufrufe. Daher hat er keinen Facebook Login und kann keine App installieren oder den standardmäßigen Facebook-OAuth-Vorgang zum Generieren eines Zugriffsschlüssels durchführen. Du musst hierfür API-Aufrufe verwenden.

Arten von System-Zugriffsschlüsseln

Art	Zugriffsschlüssel ohne Ablauf	Empfohlene Zugriffsschlüssel mit Ablauf
Lebensdauer	Läuft nie ab	60 Tage lang gültig
Aktualisierung erforderlich?	Nein	Ja
Empfehlung anhand von Anwendungsfällen	Du kannst das Risiko von gestohlenen Zugriffsschlüsseln in Kauf nehmen und möchtest, dass deine Drittanbieteranwendungen offline auf Daten zugreifen können.	Du möchtest das Risiko gestohlener Zugriffsschlüssel begrenzen.

Apps installieren

Ein Systemnutzer oder ein Systemnutzer mit Administratorrechten muss die App installieren, die zum Generieren eines Zugriffsschlüssels verwendet wird. Das bedeutet, dass der App erlaubt werden muss, APIs im Namen dieses Systemnutzers oder des Systemnutzers mit Administratorrechten aufzurufen.

Der Systemnutzer und die App sollten zum gleichen Business Manager gehören. Als Mindestanforderung für das Installieren von Apps ist Standardzugriff auf die Ads Management API erforderlich.

Voraussetzung für das Installieren einer App für einen Systemnutzer:

access_token: eines Admin-Nutzers, Systemnutzers mit Administratorrechten oder eines anderen Systemnutzers
business_app: ID der zu installierenden App

Stelle eine POST-Anfrage, um eine App für einen Systemnutzer zu installieren:

curl \
-F "business_app=APP-ID" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/applications"

Diese Anfrage gibt ein boolesches Ergebnis zurück, wenn die Installation erfolgreich war. Sollte eine der Einschränkungen nicht erfüllt werden, wird eine entsprechende Fehlermeldung angezeigt.

Zugriffsschlüssel generieren

Nachdem der Systemnutzer die App installiert hat, kann sie einen dauerhaften Zugriffsschlüssel generieren. Es gelten einige Einschränkungen:

Der Systemnutzer muss die App installiert haben, die im Parameter übergeben wird (siehe oben).
Apps können sich nur an Unternehmen (oder deren untergeordnete Unternehmen) richten, die sie beansprucht haben.
Der Systemnutzer und der Eigentümer des Zugriffsschlüssels, der während dieses API-Aufrufs zum Generieren des Zugriffsschlüssels verwendet wurde, müssen zum gleichen Business Manager gehören.
Die App kann im Besitz des gleichen Business Managers sein oder auch nicht. Ist dies nicht der Fall, gelten einige Einschränkungen. Siehe Abschnitt unten.

Parameter für den API-Aufruf:

business_app: die App, die sich im Besitz des Business Managers befindet, zu dem der Systemnutzer gehört.
appsecret_proof: berechnetes Feld für die App. Dies ist erforderlich, um sicherzustellen, dass der richtige Server den API-Aufruf durchführt. Weitere Details findest du unter Login-Sicherheit.
scope: kommagetrennter String mit erweiterten Berechtigungen.
access_token: Zugriffsschlüssel im Besitz des Business Manager-Admins, Systemnutzers mit Administratorrechten oder regulären Systemnutzers.
set_token_expires_in_60_days: Auf „true“ festgelegt, um einen Systemnutzer-Zugriffsschlüssel mit Ablauf zu generieren. Optional.

Unterstützter Umfang für Systemnutzer:

ads_management
ads_read
business_management
catalog_management
instagram_basic
instagram_content_publish
instagram_manage_comments
instagram_manage_insights
instagram_manage_messages
leads_retrieval
manage_notifications
pages_manage_cta
pages_read_engagement
pages_manage_ads
pages_manage_engagement
pages_manage_posts
pages_messaging
pages_show_list
pages_read_user_content
pages_manage_metadata
page_events
publish_video
read_audience_network_insights
read_insights
read_page_mailboxes
rsvp_event
whatsapp_business_management
whatsapp_business_messaging

Zum Generieren des appsecret_proof kannst du PHP-Code verwenden:

$appsecret_proof = hash_hmac(
  'sha256',
  $access_token_used_in_the_call,
  $app_secret_for_the_app_used_in_the_call,
);

Im Code-Beispiel oben verweist app_secret_for_the_app_used_in_the_call auf den App-Geheimcode für die App, die zum Generieren des Zugriffsschlüssels verwendet wurde. Du findest den App-Geheimcode in deinem App-Dashboard.

Der gehashte appsecret_proof sollte ein String wie der folgende sein: "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

Stelle zum Generieren eines Systemnutzer-Zugriffsschlüssels ohne Ablauf eine POST-Anfrage:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Stelle zum Generieren eines Systemnutzer-Zugriffsschlüssels mit Ablauf eine POST-Anfrage:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "set_token_expires_in_60_days=true" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Der Endpunkt hieß vorher /SYSTEM-USER-ID/ads_access_token. Ein Aufruf an diesen Namen funktioniert jedoch nicht mehr.

Die Antwort gibt den Zugriffsschlüssel-String zurück. Sollte eine der Einschränkungen nicht erfüllt werden, werden entsprechende Fehlermeldungen ausgegeben. Antwort:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

Du kannst auch über die Business Manager-Benutzeroberfläche ein Systemnutzer-Zugriffsschlüssel generieren.

Zugriffsschlüssel aktualisieren

Ein Systemnutzer-Zugriffsschlüssel ist ab dem Generierungs- oder Aktualisierungsdatum 60 Tage lang gültig. Um Kontinuität zu schaffen, sollte der*die Entwickler*in den Zugriffsschlüssel innerhalb von 60 Tagen aktualisieren. Andernfalls verfällt der Zugriffsschlüssel und der*die Entwickler*in muss einen neuen abrufen, um wieder API-Zugriff zu erhalten.

Um einen ablaufenden Systemnutzer-Zugriffsschlüssel zu aktualisieren, benötigst du Folgendes:

fb_exchange_token: Einen gültigen Systemnutzer-Zugriffsschlüssel
client_id: App-ID
client_secret: App-Geheimcode
set_token_expires_in_60_days: Auf „true“ festgelegt, um einen Systemnutzer-Zugriffsschlüssel mit Ablauf zu aktualisieren.

Frage den „GET oauth/access_token“-Endpunkt ab.

Beispielanfrage

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}&
    set_token_expires_in_60_days=true&
    fb_exchange_token={your-access-token}"

Beispielantwort

{
  "access_token":"{expiring-system-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944    // Time left in seconds until the token expires
}

Zugriffsschlüssel widerrufen

Dieser Endpunkt ist für die regelmäßige Schlüsselrotation oder das Widerrufen von Zugriffsschlüsseln für kompromittierte Systemnutzer ausgelegt, um dein System zu schützen.

Um einen Systemnutzer-Zugriffsschlüssel zu widerrufen, benötigst du Folgendes:

revoke_token: Der zu widerrufende Zugriffsschlüssel
client_id: App-ID
client_secret: App-Geheimcode
access_token: Zugriffsschlüssel zum Identifizieren des*der Aufrufer*in

Dies sind die Anforderungen:

Die client_id muss mit der tatsächlichen App übereinstimmen und du musst sicherstellen, dass die App nicht gedrosselt, deaktiviert oder gelöscht ist.
Die client_id sowie die installierte App von revoke_token, die installierte App von access_token und client_secret müssen alle gleich sein.

Frage den „GET oauth/revoke“-Endpunkt ab.

Beispielanfrage

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

Beispielantwort

{
  "success":"true",
}

Zugriffsschlüssel-Rotation

Die Schlüssel-Rotation ist eine Sicherheitsmaßnahme, die dazu beitragen kann, Risiken zu mindern (z. B. den Schaden durch gestohlene Schlüssel zu begrenzen). Durch regelmäßiges Ändern von Zugriffsschlüsseln kann der potenzielle Schaden, der durch einen gestohlenen oder abhanden gekommenen Schlüssel verursacht wird, begrenzt werden, ähnlich wie der Passwortänderung. Aktuell unterstützt unser System die Systemnutzerrotation ohne Downtime. Das geht so:

Aktualisiere den Systemnutzer-Zugriffsschlüssel über die SUAT Refresh API. Die SUAT Refresh API gibt einen neuen Systemnutzer-Zugriffsschlüssel zurück und der neue Schlüssel ist ab dem Datum der Aktualisierung 60 Tage lang gültig. Der alte Schlüssel funktioniert weiterhin bis zu seinem Ablauf (Erstellungsdatum + 60).
Stelle den neuen Systemnutzer-Zugriffsschlüssel bereit.
Widerrufe den alten Systemnutzer-Zugriffsschlüssel über die SUAT Revocation API. Der Schlüssel wird sofort ungültig und kann nach dem Widerrufen nicht mehr verwendet werden.