Permissions Reference

Permissions provide a way for your app to access data from Facebook. Getting permissions for your app, involves the following steps:

Choose the permissions that your app needs to function as intended.
If you ask for permissions other than the default profile fields, email, or pages_show_list, you must submit your app for app review so Facebook can confirm that the app uses the data in intended ways and safeguards user privacy.
When users log onto your app, they receive a request to grant the permissions your app has requested. Users can grant or deny the requested permissions or any subset of them.

To pass app review, it is important that you ask for only the permissions your app needs to function. Asking for unnecessary permissions is a common reason for rejection during app review.

For more information about permissions, see Permissions with Facebook Login.

The largest number of permissions is requested through Facebook Login, but some are requested through Instagram. In addition, businesses holding a system_user token and so functioning as a user can grant permissions through Business Manager.

For lists of permissions granted through Facebook Login and Instagram, see the following sections:

Facebook Login Permissions
Instagram Permissions

Access to any Permission that is granted by default or through App Review can be used to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

Facebook Login Permissions

Every permission below requires App Review, except: email, pages_show_list.

A

Permission	Description
ads_management	The ads_management permission allows your app to both read and manage the Ads account it owns, or has been granted access to, by the Ad account owner. Allowed Usage Programmatically create campaigns, manage ads, and fetch metrics. Build ad management tools that provide innovative solutions and differentiated value for advertisers.
ads_read	The ads_read permission allows your app to access the Ads Insights API to pull Ads report information for Ad accounts you own or have been granted access to by the owner or owners of other ad accounts through this permission. This permissions also grants your app access to the Server-Side API to allow advertisers to send web events from their servers directly to Facebook. Allowed Usage Provide API access to your ad performance data for use in custom dashboards and data analytics. Send web events from your server directly to Facebook.
attribution_read	The attribution_read permission grants your app access to the Attribution API to pull attribution report data for lines of business you own or have been granted access to by the owner or owners of other lines of business. Allowed Usage Provides the ability for your app to access ads performance data from Attribution for use in custom dashboards and data analytics.

Permission

Description

ads_management

The ads_management permission allows your app to both read and manage the Ads account it owns, or has been granted access to, by the Ad account owner.

Allowed Usage

Programmatically create campaigns, manage ads, and fetch metrics.
Build ad management tools that provide innovative solutions and differentiated value for advertisers.

ads_read

The ads_read permission allows your app to access the Ads Insights API to pull Ads report information for Ad accounts you own or have been granted access to by the owner or owners of other ad accounts through this permission. This permissions also grants your app access to the Server-Side API to allow advertisers to send web events from their servers directly to Facebook.

Allowed Usage

Provide API access to your ad performance data for use in custom dashboards and data analytics.
Send web events from your server directly to Facebook.

attribution_read

The attribution_read permission grants your app access to the Attribution API to pull attribution report data for lines of business you own or have been granted access to by the owner or owners of other lines of business.

Allowed Usage

Provides the ability for your app to access ads performance data from Attribution for use in custom dashboards and data analytics.

B

Permission	Description
business_management	The business_management permission allows your app to read and write with the Business Manager API. Allowed Usage Manage business assets such as an ad account. Claim ad accounts.

Permission

Description

business_management

The business_management permission allows your app to read and write with the Business Manager API.

Allowed Usage

Manage business assets such as an ad account.
Claim ad accounts.

C

Permission	Description
catalog_management	The catalog_management permission allows your app to create, read, update and delete business-owned product catalogs that the user is an admin of. Allowed Usage Build commerce-related solutions like ecommerce platforms, travel platforms and dynamic ads. Build inventory type management solutions like product inventory, hotel inventory or car inventory.

Permission

Description

catalog_management

The catalog_management permission allows your app to create, read, update and delete business-owned product catalogs that the user is an admin of.

Allowed Usage

Build commerce-related solutions like ecommerce platforms, travel platforms and dynamic ads.
Build inventory type management solutions like product inventory, hotel inventory or car inventory.

E

Permission	Description
email	The email permission allows your app to read a person's primary email address. Allowed Usage Communicating with people and letting them log into your app with the email address associated with their Facebook profile.

Permission

Description

The email permission allows your app to read a person's primary email address.

Allowed Usage

Communicating with people and letting them log into your app with the email address associated with their Facebook profile.

G

Permission	Description
groups_access_member_info	The groups_access_member_info permission allows your app to read publicly available group member information like name and ID if the post author has granted your app access. Allowed Usage Allow apps to get content posted in their group with user details. Help admins get aggregated insights about activity happening in their group.

Permission

Description

groups_access_member_info

The groups_access_member_info permission allows your app to read publicly available group member information like name and ID if the post author has granted your app access.

Allowed Usage

Allow apps to get content posted in their group with user details.
Help admins get aggregated insights about activity happening in their group.

I

Permission	Description
instagram_basic	The instagram_basic permission allows your app to read an Instagram account profile's info and media. Allowed Usage Get basic metadata of an Instagram Business account profile, for example username and ID.
instagram_manage_comments	The instagram_manage_comments permission allows your app to create, delete and hide comments on behalf of the Instagram account linked to a Page. Your app can also read and respond to public media and comments that a business has been photo tagged or @mentioned in. Allowed Usage Read, update and delete comments of Instagram Business accounts. Read media objects, such as stories, of Instagram Business accounts.
instagram_manage_insights	The instagram_manage_insights permission allows your app to get access to insights for the Instagram account linked to a Facebook Page. Your app can also discover and read the profile info and media of other business profiles. Allowed Usage Get metadata of an Instagram Business account. Get data insights of an Instagram Business account. Get story insights of an Instagram Business account.

Permission

Description

instagram_basic

The instagram_basic permission allows your app to read an Instagram account profile's info and media.

Allowed Usage

Get basic metadata of an Instagram Business account profile, for example username and ID.

instagram_manage_comments

The instagram_manage_comments permission allows your app to create, delete and hide comments on behalf of the Instagram account linked to a Page. Your app can also read and respond to public media and comments that a business has been photo tagged or @mentioned in.

Allowed Usage

Read, update and delete comments of Instagram Business accounts.
Read media objects, such as stories, of Instagram Business accounts.

instagram_manage_insights

The instagram_manage_insights permission allows your app to get access to insights for the Instagram account linked to a Facebook Page. Your app can also discover and read the profile info and media of other business profiles.

Allowed Usage

Get metadata of an Instagram Business account.
Get data insights of an Instagram Business account.
Get story insights of an Instagram Business account.

L

Permission	Description
leads_retrieval	The leads_retrieval permission allows your app to retrieve and read all information captured by a lead ads form associated with an ad created in Ads Manager or the Marketing API. Allowed Usage Reach out to the people who followed up your lead ad form requesting more information. For example, an auto dealer reaching out to a potential customer (lead) that responded to their ad with quotes for a car. For advertiser authorized CRM platforms to pull the lead data on behalf of the advertisers. These advertisers can then use the lead information to reach out to the user.

Permission

Description

leads_retrieval

The leads_retrieval permission allows your app to retrieve and read all information captured by a lead ads form associated with an ad created in Ads Manager or the Marketing API.

Allowed Usage

Reach out to the people who followed up your lead ad form requesting more information. For example, an auto dealer reaching out to a potential customer (lead) that responded to their ad with quotes for a car.
For advertiser authorized CRM platforms to pull the lead data on behalf of the advertisers. These advertisers can then use the lead information to reach out to the user.

P

Permission	Description
pages_manage_ads	The pages_manage_ads permission allows your app to manage ads associated with the Page. Allowed Usage Create ads for your Page. Manage ads for your Page.
pages_manage_cta	The pages_manage_cta permission allows your app to carry out POST and DELETE functions on endpoints used to manage call-to-action buttons on a Facebook Page. Allowed Usage Provide API access to manage call-to-action buttons on Pages that you manage.
pages_manage_instant_articles	The pages_manage_instant_articles permission allows your app to manage Instant Articles on behalf of Facebook Pages administered by people using your app. Allowed Usage Create and update Instant Articles for Pages owned by the people who use your app.
pages_manage_engagement	The pages_manage_engagement permission allows your app to create, edit and delete comments posted on the Page. Allowed Usage Publish a comment on a Page post. Update your comment on a Page post. Delete a comment on a Page post. Like a Page post or remove your Like from a Page post.
pages_manage_metadata	The pages_manage_metadata permission allows your app to subscribe and receive webhooks about activity on the Page, and to update settings on the Page. Allowed Usage Subscribe to receive webhooks of your Page. Update settings of your Page.
pages_manage_posts	The pages_manage_posts permission allows your app to create, edit and delete your Page posts. Allowed Usage Publish a post, photo, or video to your Page. Update a post, photo, or video on your Page. Delete a post, photo, or video on your Page.
pages_messaging	The pages_messaging permission allows your app to manage and access Page conversations in Messenger. Allowed Usage Create interactive experiences initiated by a user. Confirm customer interactions such as purchases, orders and bookings. Send customer support messages.
pages_read_engagement	The pages_read_engagement permission allows your app to read content (posts, photos, videos, events) posted by the Page, read followers data (including name, PSID), and profile picture, and read metadata and other insights about the Page. Allowed Usage Get content posted by your Page. Get names, PSIDs, and profile pictures of your Page followers. Get metadata about your Page.
pages_read_user_content	The pages_read_user_content permission allows your app to read user generated content on the Page, such as posts, comments, and ratings by users or other Pages, and to delete user comments on Page posts. Allowed Usage Get user generated content on your Page. Get posts that your Page is tagged in. Delete comments posted by users on your Page.
pages_show_list	The pages_show_list permission allows your app to access the list of the Pages that a person manages. Allowed Usage Only show a person a list of the Pages they manage unless that person gives you permission to show it to others.
pages_user_gender	The pages_user_gender permission allows your app to access a user's gender through the Page your app is connected to. Allowed Usage Personalize experiences or recommendations based on gender. Use gendered language such as correct pronouns and titles.
pages_user_locale	The pages_user_locale permission allows your to app to a user's locale through the Page your app is connected to. Allowed Usage Personalize experiences based on the locale of a person by surfacing locale specific content. Send responses in the preferred language of the person. Display numbers, times, and dates correctly for the locale of the person.
pages_user_timezone	The pages_user_timezone permission grants your app access to a user's time zone through the Page your app is connected to. Allowed Usage Prevent messages from being sent at an inconvenient time. Send time sensitive content or recurring news at a specific time. Provide tailored content based on time. Send time appropriate greetings.
publish_to_groups	The publish_to_groups permission allows your app to post content into a Group on behalf of a person if they've granted your app access. Allowed Usage Allow people to publish content from your app to their Facebook group. Help people manage the content published to their group.
publish_video	The publish_video permission allows your app to publish live videos to an app user's timeline. Allowed Usage Grants an app permission to publish live videos to the app user's timeline.

R

Permission	Description
read_insights	The read_insights permission allows your app to read the Insights data for Pages, apps and web domains the person owns. Allowed Usage Integrate Facebook's app, page or domain insights into your own analytics tools.

Permission

Description

read_insights

The read_insights permission allows your app to read the Insights data for Pages, apps and web domains the person owns.

Allowed Usage

Integrate Facebook's app, page or domain insights into your own analytics tools.

U

Permission	Description
user_age_range	The user_age_range permission allows your app to access a person's age range as listed in their Facebook profile. Allowed Usage Your app is legally required to be age-gated. Your app contains content that is not suitable for the general Facebook user base, for example dating, violent or mature content.
user_birthday	The user_birthday permission allows your app to read a person's birthday as listed in their Facebook profile. Allowed Usage Provide age-relevant content to people when their age range is not sufficient.
user_friends	The user_friends permission allows your app to get a list of a person's friends using that app. Allowed Usage Provide Facebook-related content to personalize a person's experience.
user_gender	The user_gender permission allows your app to read a person's gender as listed in their Facebook profile. Allowed Usage To render pronouns. Personalize a person's experience based on gender, for example dating, shopping and fashion apps.
user_hometown	The user_hometown permission allows your app to read a person's hometown location from their Facebook profile. Allowed Usage Provide a personalized experience based on where a person lived or grew up.
user_likes	The user_likes permission allows your app to read a list of all Facebook Pages that a user has liked. Allowed Usage Meaningfully improve the quality of a user's experience in your app (must be clear to the user how their data is used to provide that experience).
user_link	The user_link permission allows your app to access the Facebook profile URL of the person using your app. Allowed Usage Provide a way for someone who uses your app to visit another person's Facebook profile.
user_photos	The user_photos permission allows your app to read the photos a person has uploaded to Facebook. Allowed Usage Create physical or digital books or albums of a person's photos, which includes permitting people to export photos for printing. Provide people with the ability to display their photos with other app users, for example in dating or social apps. Provide people with the ability to edit or create new photo content based on existing photos.
user_posts	The user_posts permission allows your app to access the posts that a user has made on their timeline. Allowed Usage Meaningfully improve the quality of a user's experience in your app (must be clear to the user how their data is used to provide that experience).
user_videos	The user_videos permission allows your app to read a list of videos uploaded by a person. Allowed Usage Display a person's videos on a TV via a set-top box or in a digital photo frame. Provide people with the ability to edit or create new video content using existing videos. Provide people with the ability to display their video with owners within their app, for example in dating or social apps.

W

Permission	Description
whatsapp_business_management	The whatsapp_business_management permission allows your app to read and/or manage WhatsApp business assets you own or have been granted access to by other businesses through this permission. Allowed Usage Display WhatsApp Business Account analytics in your customer portal. Manage message templates for WhatsApp Business Accounts.

Permission

Description

whatsapp_business_management

The whatsapp_business_management permission allows your app to read and/or manage WhatsApp business assets you own or have been granted access to by other businesses through this permission.

Allowed Usage

Display WhatsApp Business Account analytics in your customer portal.
Manage message templates for WhatsApp Business Accounts.

Deprecated Permissions

Permission	Description
manage_pages	Deprecated for v7.0+.
publish_pages	Deprecated for v7.0+.

Instagram Permissions

Permission	Description
instagram_graph_user_media	The instagram_graph_user_profile permission allows your app to read the app user's profile. Allowed Usage Creating physical or digital books from the app user's photos, including exporting photos for printing. Displaying the app users photos to other app users within the app, for example with social or dating apps. Editing or creating new photos or videos based on the app user's existing photos and videos, (e.g. for photo or video Editing Apps). Displaying the app user's photos and videos in an external device such as a TV or digital photo frame.
instagram_graph_user_profile	The ads_read permission allows your app to access the Ads Insights API to pull Ads report information for Ad accounts you own or have been granted access to by the owner or owners of other ad accounts through this permission. This permissions also grants your app access to the Server-Side API to allow advertisers to send web events from their servers directly to Facebook. Allowed Usage Read fields in an Instagram user profile, for example user ID and account type.

Permission

Description

instagram_graph_user_media

The instagram_graph_user_profile permission allows your app to read the app user's profile.

Allowed Usage

Creating physical or digital books from the app user's photos, including exporting photos for printing.
Displaying the app users photos to other app users within the app, for example with social or dating apps.
Editing or creating new photos or videos based on the app user's existing photos and videos, (e.g. for photo or video Editing Apps).
Displaying the app user's photos and videos in an external device such as a TV or digital photo frame.

instagram_graph_user_profile

Allowed Usage

Read fields in an Instagram user profile, for example user ID and account type.