Установка приложений, генерация, обновление и отзыв маркеров

Системный пользователь — это не реальный человек, а объект, представляющий вызовы сервера, поэтому он не может войти в Facebook, установить приложение или выполнить стандартную процедуру oAuth, чтобы сгенерировать маркер. Вы должны сделать это с помощью вызовов API.

Типы системных маркеров доступа

Типы	Маркеры доступа без срока действия	Рекомендуемые маркеры доступа со сроком действия
Пожизненный	Не истекает никогда	Действует 60 дней
Нужно обновлять?	Нет	Да
Рекомендации на основании сценариев использования	Необходимо учесть риски в случае утечки маркеров доступа и обеспечить офлайн-доступ к данным для сторонних приложений.	Необходимо снизить риск утечки маркеров доступа.

Установка приложений

Системный пользователь или системный пользователь-администратор должен установить приложение, которое будет использоваться для создания маркера доступа. Это значит, что приложению будет разрешено вызывать API от имени этого пользователя.

Системный пользователь и приложение должны принадлежать к одному аккаунту Business Manager. Устанавливать можно только приложения со стандартным или более высоким уровнем доступа к API Ads Management.

Чтобы установить приложение для системного пользователя, вам понадобятся:

access_token: маркер доступа администратора, системного пользователя-администратора или другого системного пользователя;
business_app: ID устанавливаемого приложения.

Чтобы установить приложение для системного пользователя, выполните запрос POST:

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

Если приложение будет установлено, этот вызов вернет логическое значение. Если какие-либо ограничения не соблюдены, вы увидите соответствующее сообщение об ошибке.

Создание маркера доступа

Когда приложение будет установлено, системный пользователь сможет создать постоянный маркер доступа. Здесь действует ряд ограничений:

У системного пользователя должно быть установлено приложение, переданное в параметре (см. выше).
Приложение может быть доступно только компаниям, которым оно принадлежит (или их дочерним компаниям).
Системный пользователь и владелец маркера доступа, использованного в этом вызове API, должны принадлежать к одному аккаунту Business Manager.
Владельцем приложения не обязательно должен быть тот же аккаунт Business Manager. Если аккаунт не является владельцем приложения, действуют некоторые ограничения. Подробнее об этом см. в разделе ниже.

Параметры для вызова API:

business_app — приложение, связанное с аккаунтом Business Manager, к которому относится системный пользователь;
appsecret_proof — вычисленное поле для приложения, позволяющее системе убедиться, что вызов API получен от корректного сервера (подробные сведения см. в статье об обеспечении безопасности входа);
scope: строка, содержащая расширенные разрешения с разделителями-запятыми;
access_token — маркер, принадлежащий администратору Business Manager, системному пользователю-администратору или обычному системному пользователю.
set_token_expires_in_60_days — установите значение true, чтобы сгенерировать маркер доступа со сроком действия Необязательно.

Системным пользователям доступны перечисленные далее разрешения.

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

Устаревшее разрешение, отображается только для тех приложений, которые созданы до 24 апреля 2018 г.

publish_actions

Разрешения с ограничением по возможностям

Возможность	Разрешение
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`

Чтобы сгенерировать appsecret_proof, можно использовать код PHP:

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

В примере кода выше app_secret_for_the_app_used_in_the_call обозначает секрет приложения, с помощью которого генерируется маркер доступа. Секрет приложения можно найти на панели приложений.

Хэшированное значение appsecret_proof представляет собой строку наподобие "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

Чтобы создать бессрочный маркер доступа системного пользователя, выполните запрос 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"

Чтобы создать маркер доступа системного пользователя со сроком действия, выполните запрос 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"

Раньше конечная точка называлась /SYSTEM-USER-ID/ads_access_token. Теперь вызов к этому имени не работает.

Ответ будет содержать строку с маркером доступа. Если какие-либо ограничения не соблюдены, будут возвращены соответствующие коды ошибок. Ответ:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

Маркер доступа системного пользователя также можно сгенерировать с использованием Business Manager.

Обновление маркера доступа

Маркер доступа системного пользователя со сроком действия действителен в течение 60 дней с даты генерации или обновления. Чтобы обеспечить непрерывную работу, разработчик должен обновить маркер доступа в течение 60 дней. Если этого не сделать, маркер доступа будет утрачен, и разработчику потребуется получить новый маркер, чтобы восстановить доступ к API.

Чтобы обновить маркер доступа системного пользователя со сроком действия, вам понадобятся:

fb_exchange_token — действительный маркер доступа системного пользователя;
client_id — ID приложения;
client_secret — секрет приложения;
set_token_expires_in_60_days — установите значение true, чтобы обновить маркер доступа со сроком действия.

Отправьте запрос GET к конечной точке oauth/access_token.

Пример запроса

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

Пример ответа

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

Отзыв маркера доступа

Эта конечная точка предназначена для выполнения регулярной ротации маркеров или отзыва маркеров доступа для скомпрометированных системных пользователей в качестве способа защиты вашей системы.

Чтобы отозвать маркер доступа системного пользователя, вам понадобятся:

revoke_token — маркер доступа, который необходимо отозвать;
client_id — ID приложения;
client_secret — секрет приложения;
access_token — маркер доступа для идентификации участника вызова.

Должны быть соблюдены следующие требования:

Значение client_id должно соответствовать фактическому приложению и гарантировать, что приложение не имеет ограничений, не отключено или не удалено.
Значение client_id, как и установленное приложение маркера revoke_token, установленное приложение маркера access_token и секрет client_secret, должны быть одинаковыми.

Отправьте запрос GET к конечной точке oauth/revoke.

Пример запроса

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

Пример ответа

{
  "success":"true",
}

Ротация маркера доступа

Ротация маркера — это мера предосторожности, которая может помочь уменьшить риски, например ограничить ущерб в случае утечки маркеров. Регулярное изменение маркеров доступа может ограничить потенциальный ущерб, вызванный утечкой или неправильным расположением маркера, и во многом похоже на смену пароля. В настоящий момент наша система поддерживает ротацию системных пользователей без простоев. Для этого соблюдайте следующие инструкции:

Обновите маркер доступа системного пользователя, используя API SUAT Refresh. API SUAT Refresh вернет новый маркер доступа системного пользователя, который будет действителен в течение 60 дней со дня своего обновления. Старый маркер по-прежнему будет работать до истечения срока действия его (дата создания + 60 дней).
Используйте новый маркер доступа системного пользователя.
Отзовите старый маркер доступа системного пользователя, используя API SUAT Revocation. Маркера аннулируется сразу же. После отзыва использовать его будет невозможно.