Installer des applications, et générer, actualiser et révoquer des tokens

Puisqu’un·e utilisateur·ice système représente les appels de serveur, il ou elle n’intègre pas Facebook Login et ne peut pas installer des applications, ni passer par le processus OAuth standard de Facebook pour générer un token. Vous devez procéder par le biais d’appels d’API.

Types de tokens d’accès système

Types	Token d’accès sans expiration	Token d’accès avec expiration suggéré
Durée de vie	N’expire jamais	Validité de 60 jours
Actualisation requise ?	Non	Oui
Recommandation selon les cas d’utilisation	Vous estimez tolérable le risque que des tokens d’accès soient divulgués et souhaitez que des applications tierces puissent accéder hors ligne à des données.	Vous souhaitez limiter le risque de divulgation des tokens d’accès.

Installer des applications

Un·e utilisateur·ice système ou un·e utilisateur·ice système admin doit installer l’application qui sera utilisée pour générer un token d’accès. Cela implique d’autoriser l’application à appeler des API au nom de cet·te utilisateur·ice système ou de cet·te utilisateur·ice système admin.

L’utilisateur·ice système et l’application doivent tous deux appartenir à un même compte Business Manager. Seules les applications disposant d’un accès standard ou supérieur au sein de l’API Ads Management peuvent être installées.

Pour installer une application pour un·e utilisateur·ice système, vous devez disposer des éléments suivants :

access_token : token d’accès d’un·e utilisateur·ice admin, d’un·e utilisateur·ice système admin ou d’un·e autre utilisateur·ice système ;
business_app : ID de l’application à installer.

Pour installer une application pour un·e utilisateur·ice système, envoyez une requête POST :

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

Cet appel renvoie un résultat booléen si l’installation réussit. Lorsque l’une des restrictions n’est pas respectée, vous recevez un message d’erreur pertinent.

Générer un token d’accès

Une fois que l’utilisateur·ice système a installé l’application, celle-ci peut générer un token d’accès permanent. Certaines restrictions s’appliquent :

L’utilisateur·ice système doit avoir installé l’application transmise dans le paramètre, comme indiqué à l’étape précédente.
Les applications peuvent uniquement cibler les entreprises (ou filiales de ces entreprises) qui les ont réclamées.
L’utilisateur·ice système et le ou la propriétaire du token d’accès utilisé lors de cet appel d’API de génération de tokens doivent appartenir au même compte Business Manager.
L’application peut appartenir ou non au même compte Business Manager. Si ce n’est pas le cas, certaines restrictions s’appliquent. Consultez la section ci-dessous.

Les paramètres de l’appel d’API sont les suivants :

business_app : application appartenant ou transmise au compte Business Manager auquel l’utilisateur·ice système appartient.
appsecret_proof : champ calculé pour l’application. Cet élément est nécessaire pour faire en sorte que l’appel d’API provienne du bon serveur. Pour plus d’informations, consultez la page Sécurité de la connexion.
scope : chaîne séparée par des virgules contenant des autorisations étendues.
access_token : token appartenant à l’admin Business Manager, à l’utilisateur·ice système admin ou à un·e utilisateur·ice système standard.
set_token_expires_in_60_days : défini sur true pour générer un token d’accès d’utilisateur·ice système avec expiration. Facultatif.

Les champs d’application pris en charge pour les utilisateur·ices système sont les suivants :

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

Pour générer un élément appsecret_proof, vous pouvez utiliser un code PHP :

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

Dans l’exemple de code ci-dessus, app_secret_for_the_app_used_in_the_call correspond à la clé secrète de l’application utilisée pour générer le token d’accès. Votre clé secrète se trouve dans votre Espace App.

L’élément appsecret_proof haché doit correspondre à une chaîne telle que "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

Pour générer un token d’accès d’utilisateur·ice système permanent, envoyez une requête POST :

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"

Pour générer un token d’accès d’utilisateur·ice système avec expiration, envoyez une requête POST :

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"

Auparavant, le point de terminaison se nommait /SYSTEM-USER-ID/ads_access_token. Adresser un appel à ce nom ne fonctionne plus.

La réponse renvoie la chaîne du token d’accès. Si les restrictions ne sont pas respectées, les codes d’erreur appropriés sont générés. Réponse :

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

Vous pouvez aussi générer un token d’accès d’utilisateur·ice système via l’UI Business Manager.

Actualiser un token d’accès

Une fois généré ou actualisé, un token d’utilisateur·ice système avec expiration est valable 60 jours. Pour assurer la continuité, le développeur ou la développeuse doit actualiser le token d’accès dans un délai de 60 jours et en obtenir un nouveau pour récupérer l’accès à l’API.

Pour actualiser un token d’accès d’utilisateur·ice système avec expiration, vous aurez besoin des éléments suivants :

fb_exchange_token : un token d’accès d’utilisateur·ice système valide
client_id : ID d’application
client_secret : clé secrète
set_token_expires_in_60_days : défini sur true pour actualiser un token d’accès d’utilisateur·ice système avec expiration.

Envoyez une requête GET au point de terminaison oauth/access_token.

Exemple de requête

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

Exemple de réponse

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

Révoquer un token d’accès

Ce point de terminaison est prévu pour réaliser la rotation régulière des tokens ou pour révoquer les tokens d’accès d’utilisateur·ice système compromis de manière à protéger votre système.

Pour actualiser un token d’accès d’utilisateur·ice système avec expiration, vous aurez besoin des éléments suivants :

revoke_token : token d’accès à révoquer
client_id : ID d’application
client_secret : clé secrète
access_token : token d’accès permettant d’identifier l’auteur de l’appel

Les conditions requises sont les suivantes :

Le client_id doit correspondre à l’application réelle, et vous devez vérifier que l’application n’est pas régulée, désactivée ou supprimée.
Le client_id, l’application installée associée à revoke_token, l’application installée associée à access_token ainsi que client_secret doivent tous être identiques.

Envoyez une requête GET au point de terminaison oauth/revoke.

Exemple de requête

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

Exemple de réponse

{
  "success":"true",
}

Rotation des tokens d’accès

Cette mesure de sécurité permet de réduire les risques, par exemple en minimisant les conséquences d’une divulgation de tokens. Modifier régulièrement les tokens d’accès, tout comme les mots de passe, permet de limiter les préjudices qu’une divulgation ou une perte de tokens pourrait causer. Actuellement, notre système permet d’effectuer une rotation des tokens d’utilisateur·ice système sans interruption. Pour ce faire, suivez les instructions ci-après :

Actualisez le token d’accès d’utilisateur·ice système via l’API SUAT Refresh. L’API SUAT Refresh renvoie à un nouveau token d’accès d’utilisateur·ice système qui est valable 60 jours à compter de la date d’actualisation. L’ancien token reste valable jusqu’à son expiration (60 jours après sa date de création).
Déployez le nouveau token d’accès d’utilisateur·ice système.
Révoquez l’ancien token d’accès d’utilisateur·ice système via l’API SUAT Refresh. Le token est révoqué immédiatement et ne peut plus être utilisé.