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

Puisqu’un utilisateur 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 utilisateur système ou un utilisateur 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 utilisateur système ou de cet utilisateur système admin.

L’utilisateur 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 utilisateur système, vous devez disposer des éléments suivants :

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

Pour installer une application pour un utilisateur 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 système a installé l’application, celle-ci peut générer un token d’accès permanent. Certaines restrictions s’appliquent :

L’utilisateur 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 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 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. Recommandé. Les tokens avec expiration sont une recommandation en matière de sécurité. Certaines entreprises doivent utiliser des tokens avec expiration. Si cette exigence s’applique à votre entreprise, l’omission de ce paramètre ou sa définition sur false entraînera une erreur. Toutes les intégrations doivent adopter des tokens qui arrivent à expiration pour s’aligner sur les normes de sécurité en constante évolution de la plateforme.

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

ads_management
ads_read
attribution_read
business_management
catalog_management
commerce_account_manage_orders
commerce_account_read_orders
commerce_account_read_settings
instagram_basic
instagram_branded_content_ads_brand
instagram_branded_content_brand
instagram_content_publish
instagram_manage_comments
instagram_manage_insights
instagram_manage_messages
instagram_shopping_tag_products
leads_retrieval
page_events
pages_manage_ads
pages_manage_cta
pages_manage_engagement
pages_manage_instant_articles
pages_manage_metadata
pages_manage_posts
pages_messaging
pages_read_engagement
pages_read_user_content
pages_show_list
private_computation_access
publish_video
read_audience_network_insights
read_insights
read_page_mailboxes
whatsapp_business_management
whatsapp_business_messaging

Autorisation obsolète, uniquement visible par les applications créées avant le 24 avril 2018

publish_actions

Autorisations liées aux fonctionnalités

Fonctionnalité	Autorisation
business_creative_asset_management	`business_creative_managementbusiness_creative_insights` `business_creative_insights_sharebusiness_data_management`
commerce_public_api_beta_testing	`commerce_manage_accountscommerce_account_read_reports`

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 système permanent, envoyez une requête POST :

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,pages_read_engagement,pages_show_list" \
-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 système avec expiration, envoyez une requête POST :

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,pages_read_engagement,pages_show_list" \
-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 système via l’UI Business Manager.

Actualiser un token d’accès

Une fois généré ou actualisé, un token d’utilisateur 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 système avec expiration, vous aurez besoin des éléments suivants :

fb_exchange_token : un token d’accès d’utilisateur 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 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 système compromis de manière à protéger votre système.

Pour actualiser un token d’accès d’utilisateur 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 système sans interruption. Pour ce faire, suivez les instructions ci-après :

Actualisez le token d’accès de l’utilisateur système via l’API Refresh, qui renvoie un nouveau token d’accès d’utilisateur·ice système valable pendant 60 jours à compter de la date d’actualisation. L’ancien token d’accès 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é.