Facebook
Permissions Reference for Meta Technologies APIs
Permissions are a form of granular, user-granted Graph API authorization. Before your app can use an endpoint to access an app user's data, the app user must grant your app all permissions required by that endpoint.
You may also use any permission granted to your app 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).
Requirements
- App Review
is required for all permissions
except for emailandpublic_profileif your app needs access to data that you do not own or manage - Only select permissions that your app needs to function as intended. Selecting unneeded permissions is a common reason for rejection during app review
- If your app requests permission to use an endpoint to access an app user’s data, you may need to complete data handling questions.
- You may also be required to complete an annual Data Use Checkup.
Ways to ask for a permission
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.
If your app does not use a permission for 90 days, usually due to user inactivity, the app user must regrant your app that permission.
Remove a permission
You can use the app dashboard to remove a permission your app no longer uses or to remove a permission that has been deprecated.
A
Permission
Description
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.
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.
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.
C
Permission
Description
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.
The commerce_account manage_orders
permission allows your app to read and update commerce account orders.
Allowed Usage
- Read and update orders in your commerce account.
- Tech providers manage orders on behalf of their customers.
- Access to Webhook notifications.
The commerce_account_read_orders
permission allows your app to read commerce account orders.
Allowed Usage
- Read orders in your commerce account.
- Use the buyer's email address for marketing purposes only if a buyer has opted-in at checkout.
The commerce_account_read_reports
permission allows your app to read finance reporting data to build custom tax, cash reconciliation and reimbursement reports for a commerce account.
Allowed Usage
- Read finance reporting data in your commerce account for building custom tax cash reconciliation and reimbursement reports.
- Tech providers can run finance reports on behalf of their customers.
The commerce_account_read_settings
permission allows your app to read commerce account settings.
Allowed Usage
- Read basic commerce account information like connected channels, shipping options, fulfillment locations, connected business, etc.
The commerce_manage_accounts
permission allows your app to create and manage commerce accounts, such as an ecommerce app.
Allowed Usage
- Associate your app with your commerce account.
- Tech providers create a commerce account on behalf of their customers.
- Tech providers enable a new sales channel within their customer’s commerce account.
I
Permission
Description
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.
The instagram_branded_content_ads_brand
permission allows an app to read Instagram posts where the app user's Instagram account is tagged as a paid partner, and an app user to read, request, and revoke permissions to run Partnership Ads.
Allowed Usage
- Read Instagram posts where the account is tagged as a paid partner
- Manage permissions to run Partnership Ads without needing a pre-existing post
The instagram_branded_content_brand
permission allows your app to add, remove and view creators from a specific brand’s approved creators list. The allowed usage for this permission is to manage a specific brand’s Instagram creator content settings. You may also use this permission 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).
Allowed Usage
- Manage branded creator content settings on a business’ Instagram account.
The instagram_branded_content_creator
permission allows your app to read and change the boost status of a creator’s specific piece of content. The allowed usage for this permission is to manage Instagram creator content settings. You may also use this permission 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).
Allowed Usage
- Read and change an Instagram creator’s content settings.
The instagram_business_basic
allows your app to read an Instagram Business account profile's info and media. The allowed usage for this permission is to get basic metadata of an Instagram Business account profile, for example username and ID.
Allowed Usage
- Get basic metadata of an Instagram Business account profile
The instagram_business_content_publish
permission allows an app to create organic feed photo and video posts on behalf of a business user. The allowed usage of this permission is to allow an app to manage the organic content creation process for Instagram (for example, post photos and videos) on behalf of an Instagram business account. You may also use this permission 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).
Allowed Usage
- Manage the organic content creation process for Instagram (for example, post photos and videos) on behalf of an Instagram business account
The instagram_business_manage_comments
permission allows an app to access comments on an Instagram professional account, as well as public posts and Instagram Stories where that account is tagged or mentioned in comments. The allowed usage for this permission is to create, update and delete comments for an Instagram professional account.
Allowed Usage
- Create, update, and delete comments for an Instagram professional account
The instagram_business_manage_messages
permission allows an app to access messages on an Instagram professional account. The allowed usage for this permission is to view, manage and respond to messages, and to use third-party customer relationship management (CRM) tools to manage messages.
Allowed Usage
- View, manage, and respond to messages
- Use third-party customer relationship management (CRM) tools to manage messages
The instagram_content_publish
permission allows your app to create organic feed photo and video posts on behalf of a business user.
Allowed Usage
- Managing organic content creation process for Instagram (for example, post photos and videos to main feed) on behalf of a business.
The instagram_graph_user_media
permission allows your app to read the Media node, which represents an image, video, or album and the node’s edges.
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.
The instagram_graph_user_profile
permission allows your app to read the app user's profile.
Allowed Usage
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.
The instagram_manage_events
permission allows an app permission to log events (e.g., purchase, add-to-cart, leads) on behalf of Instagram accounts administered by the app’s users. The allowed usage for this permission is to log events on Instagram accounts and send this activity data to Meta for ads targeting, optimization and reporting; and to provide marketing and advertising analytics insights. You may also use this permission 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).
Allowed Usage
- Log events on Instagram accounts and send this activity data to Meta for ads targeting, optimization and reporting
- Provide marketing and advertising analytics 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.
The instagram_manage_messages
permission allows business users to read and respond to Instagram Direct messages.
Allowed Usage
- Business that want to retrieve threads and messages from its Direct inbox.
- Business that want to manage messages with their customer.
- Business that want to use third-party customer relationship management (CRM) tools to manage its IG Direct inbox.
The instagram_shopping_tag_products
permission allows an app to tag Instagram media with product tags and appeal product rejections.
Allowed Usage
- Check eligibility for product tagging
- Get catalogs and products
- Tag media with product tags
- Manage existing product tags
- Appeal product rejections
The instagram_manage_upcoming_events
permission allows an app to read, create, and update upcoming events on behalf of Instagram accounts administered by people using the app. The allowed usage for this permission is to manage upcoming events on Instagram accounts administered by the people using the app. You may also use this permission 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).
Allowed Usage
- Manage upcoming events on Instagram accounts administered by the people using the app
L
Permission
Description
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.
M
Permission
Description
The manage_app_solution
permission allows an app to get a list of apps that a user can manage, and make API calls on behalf of those apps. The allowed usage for this permission is to let a business create and manage partner solutions between Tech Providers and Solution Partners.
Allowed Usage
- Let a business create and manage partner solutions between Tech Providers and Solution Partners
The manage_fundraisers
permission allows an app to create, update, and read a fundraiser and its donations on behalf of a user.
Allowed Usage
- Help fundraiser creators to expand their reach on Facebook.
- Sync the amount raised displayed on the fundraiser's website and the linked Facebook fundraiser.
P
Permission
Description
The page_events
permissions allows your app permission to log events on behalf of Facebook Pages administered by people using your app and to send those events to Facebook for ads targeting, optimization and reporting.
Allowed Usage
- Send businesses related activities (for example purchase, add-to-cart, lead) on behalf of Pages owned by the people who use your app.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The pages_show_list
permission allows your app to access the list of Pages a person manages.
Allowed Usage
- Show a person the list of Pages they manage.
- Verify that a person manages a Page.
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.
The pages_user_locale
permission allows your app to access 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.
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.
The private_computation_access
permission allows an app to access the Meta Private Computation products.
Allowed Usage
- Monitor private attribution datasets for a business.
- Monitor instances for private attribution datasets for a business.
- Create and manage instances for private attribution datasets for a business.
The public_profile
permission allows an app to read the Default Public Profile Fields
on the User
node. This permission is automatically granted to all apps.
Allowed Usage
- Authenticate app users and provide them with a personalized in-app experience.
T
Permission
Description
The threads_basic
permission allows an app to get a user's Threads profile information and the media and text content that they posted to Threads. The allowed usage for this permission is to display a user’s own Threads posts within an app, and make these visible only to the user who created them. You may also use this permission 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).
Allowed Usage
- Display a user’s own Threads posts within an app, and make these visible only to the user who created them
The threads_content_publish
permission allows an app to create and publish content on behalf of a Threads profile. The allowed usage for this permission is to enable an app user to create and publish content to their Threads profile. You may also use this permission 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).
Allowed Usage
- Enables an app user to create and publish content to their Threads profile
The threads_manage_insights
permission allows your app to get access to insights for a Threads profile. The allowed usage for this permission is to allow your app to get insights for a Threads profile and for individual threads published by that profile. You may also use this permission 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).
Allowed Usage
- Get insights for a Threads profile
- Get insights for individual threads published by that profile
The threads_manage_replies
permission allows an app to create a reply on behalf of a Threads profile, hide or unhide replies to a thread, and control who can reply to a thread on the Threads profile. The allowed usage of this permission is to allow an app to create a reply on behalf of a Threads profile, hide or unhide replies to a thread, and control who can reply to a thread on the Threads profile. You may also use this permission 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).
Allowed Usage
- Create a reply on behalf of a Threads profile
- Hide or unhide replies to a thread
- Control who can reply to a thread on the Threads profile
The threads_read_replies
permission allows an app to read replies to a user's thread. The allowed usage for this permission is to get replies to a thread owned by the app user. You may also use this permission 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).
Allowed Usage
- Get replies to a thread owned by the app user
U
Permission
Description
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.
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.
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.
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.
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.
The user_likes
permission allows your app to read a list of all Facebook Pages that a user has liked.
Allowed Usage
- Provide a personalized experience by correlating or surfacing content related to the person’s likes. This includes curating content at scale to customize apps with large amounts of content and to enable people to share their likes with others, such as in the case of dating and music apps.
- Allow parental access controls and monitoring apps to analyze user likes for potential safety and wellbeing issues for people under 18 years old, as used solely by parents and guardians for under 18 year old dependents and limited to youth social media analysis as presented in the app’s user interface.
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.
The user_location
permission allows your app to read the city name as listed in the location field of a person's Facebook profile.
Allowed Usage
- Provide a personalized experience based on the city name as listed in the location field of a person's Facebook profile.
The user_messenger_contact
permission allows a business to contact a person via Messenger upon their approval or initiation of a chat thread with the business's Page.
Allowed Usage
- For a Page to send a person an initial message, post-purchase updates and account updates.
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.
The user_posts
permission allows your app to access the posts that a user has made on their timeline.
Allowed Usage
- Enable people to create physical or digital books or albums of their timelines, and to share memories from their timeline on Facebook or on other social apps.
- Allow parental access controls and monitoring apps to analyze a post's content to detect potential risk to safety or wellbeing for people under 18 years old, as used solely by parents and guardians for under 18 year old dependents and limited to youth social media analysis as presented in the app’s user interface.
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
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. These business assets include WhatsApp Business Accounts, business phone numbers, message templates, QR codes and their associated messages, and webhook subscriptions.
Allowed Usage
- Manage WhatsApp business assets.
- Display WhatsApp Business Account analytics in your customer portal.
The whatsapp_business_messaging
permission allows an app to send WhatsApp messages to a specific phone number, upload and retrieve media from messages, manage and get WhatsApp business profile information, and to register those phone numbers with Meta.
Allowed Usage
- Send WhatsApp messages to a specific phone number
- Upload and retrieve media from messages
- Manage and get WhatsApp business profile information
- Register a phone number with Meta
Permission Dependencies
To use certain permissions when your app goes live, your app must also be approved for additional permissions. These dependent permissions must have been approved either during the same app review submission or a in previous submission.
| Permission | Dependent on |
|---|---|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
