Permissions Reference - Facebook Login
Each permission has its own set of requirements and suggested use cases. All these permissions, except the default, public_profile, require that you have Client OAuth Login enabled for your app on the Facebook Login tab of your app dashboard. Some permissions do not require review, but most do. Please see the details for each permission to learn more about how to use it in your app. Remember, all use of these permissions are subject to our Platform Policies and your own privacy policy.
Deprecated Permissions
public_profile (Default)
Provides access to a subset of items that are part of a person's public profile. A person's public profile refers to the following properties on the user object by default:
idcovernamefirst_namelast_nameage_rangelinkgenderlocalepicturetimezoneupdated_timeverified
On the web, public_profile is implied with every request and isn't required, although the best practice is to declare it. On iOS and Android, you must manually request it as part of your login flow.
gender & locale can only be accessed if:
- The person queried is the person using the app.
- The person queried is using the app, and is a friend of the person using the app.
- The person queried is using the app, is not a friend of the person using the app, but the app includes either an app access token or an
appsecret_proofargument with the call.
timezone & verified can only be accessed if:
- The person queried is equal to the person making the request.
Review
Your app may use this permission without review from Facebook.
user_friends
Provides access the list of friends that also use your app. These friends can be found on the friends edge on the user object.
In order for a person to show up in one person's friend list, both people must have decided to share their list of friends with your app and not disabled that permission during login. Also both friends must have been asked for user_friends during the login process.
Review
Your app may use this permission without review from Facebook.
Common Usage
Use the list of friends to create a social experience in your app.
email
Provides access to the person's primary email address via the email property on the user object.
Do not spam users. Your use of email must comply with both Facebook policies and with the CAN-SPAM Act.
Note, even if you request the email permission it is not guaranteed you will get an email address. For example, if someone signed up for Facebook with a phone number instead of an email address, the email field may be empty.
Review
Your app may use this permission without review from Facebook.
Extended Profile Properties
These permissions are not optional in the login dialog during the login flow, meaning they are non-optional for people when logging into your app. If you want them to be optional, you should structure your app to only request them when absolutely necessary and not during initial login.
user_about_me
Provides access to a person's personal description (the 'About Me' section on their Profile) through the User object.
This permission does not give access to a person's public profile data. A person's name, profile picture, locale, age range and gender are included by default with the public_profile permission.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Enhance a person's profile within your app by surfacing the 'about me' information from their Facebook Profile.
Determine basic profile information; this is included in public_profile which is granted by all those who log into your app.
user_actions.books
Provides access to all common books actions published by any app the person has used. This includes books they've read, want to read, rated or quoted.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Personalize a person's experience based on the books they've read, want to read, rated or quoted.
Recommend books to read based on the books they've previously read.
user_actions.fitness
Provides access to all common Open Graph fitness actions published by any app the person has used. This includes runs, walks and bikes actions.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Personalize a person's experience based on their fitness activity.
Display a person's aggregate fitness activity over time.
Show how someone's fitness activity compares to other people who use your app.
Help people set and achieve personal fitness goals.
user_actions.music
Provides access to all common Open Graph music actions published by any app the person has used. This includes songs they've listened to, and playlists they've created.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Recommend people music based on what they've listened to in the past.
Connect people with concerts/events and other content based on what they've listened to.
Help people understand what their top artists and albums are.
user_actions.news
Provides access to all common Open Graph news actions published by any app the person has used which publishes these actions. This includes news articles they've read or news articles they've published.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Surfacing relevant books, articles or events, visibly providing a more tailored content experience.
Personalize a person's experience based on their news activity.
user_actions.video
Provides access to all common Open Graph video actions published by any app the person has used which publishes these actions. This includes videos they've watched, videos they've rated and videos they want to watch.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Surfacing videos, movies and TV shows the person has interacted with, visibly providing a more tailored content experience.
Personalize a person's experience based on the movies, TV shows and videos they've watched.
user_actions:{app_namespace}
Provides access to all of the person's custom Open Graph actions in the given app.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Personalize a person's experience based on their open graph actions published by another app.
user_birthday
Access the date and month of a person's birthday. This may or may not include the person's year of birth, dependent upon their privacy settings and the access token being used to query this field.
Please note most integrations will only need age_range which comes as part of the public_profile permission.
Review
If your app requests this permission Facebook will have to review how your app uses it.
When submitting for review, please be clear as to why age_range is not sufficient for your use case.
Common Usage
Provide age relevant content to people based on their date of birth information.
Provide age relevant content for anything where the age range is not sufficient.
Determine whether a person says they are under 18, over 18 or over 21. Please use the age_range field which is provided as a part of the public_profile permission, for which no review is needed before use.
user_education_history
Provides access to a person's education history through the education field on the User object.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Surface content of relevance to alumni.
Help people connect with other people with a common education history.
Calculate analytics that are not clearly visible in app.
user_events
Provides read-only access to the Events a person is hosting or has RSVP'd to.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Reduce friction in the visibility of calendar and event information (e.g. device apps, planner apps, concert apps)
Does not allow you to create events. It is not possible to create events via the Graph API.
Allow someone to RSVP to events using your app. For this, request the rsvp_event permission.
user_games_activity
Provides access to read a person's game activity (scores, achievements) in any game the person has played.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Provide an intuitive list of game achievements or general access to the games API.
Analytics purposes that are not clearly visible in app.
user_groups
This permission is only available for apps using Graph API version v2.3 or older.
Enables your app to read the Groups a person is a member of through the groups edge on the User object.
This permission does not allow you to create groups on behalf of a person. It is not possible to create groups via the Graph API.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Limited Use
This permission is granted to apps building a Facebook-branded client on platforms where Facebook is not already available. For example, Android and iOS apps will not be approved for this permission. In addition, Web, Desktop, in-car and TV apps will not be granted this permission.
user_hometown
Provides access to a person's hometown location through the hometown field on the User object. This is set by the user on the Profile.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Personalize a person's experience based on where they lived or grew up.
Help people connect to others from their hometown.
user_likes
Provides access to the list of all Facebook Pages and Open Graph objects that a person has liked. This list is available through the likes edge on the User object.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Creating a personalized experience by surfacing content related to a person's activities.
Visibly enable connections with other users with mutual interests.
Gate access to your app, or some content within your app based on whether or not someone has liked a page.
user_location
Provides access to a person's current city through the location field on the User object. The current city is set by a person on their Profile.
The current city is not necessarily the same as a person's hometown.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Personalize a person's experience based on their current city.
Surface content relevant to their city.
Help people connect to others from their city.
user_managed_groups
Lets your app read the content of groups a person is an admin of through the Groups edge on the User object.
This permission does not allow you to create groups on behalf of a person. It is not possible to create groups via the Graph API. This does not let you read the groups a user is just a member of.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Limited Use
Provide an interface to help a person manage multiple groups.
Publish posts into a group a person manages (also requires the publish_actions permission).
Non-visible use of this data such as sentiment analysis or guarding against spam bots.
user_photos
Provides access to the photos a person has uploaded or been tagged in. This is available through the photos edge on the User object.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Display a person's pictures on digital photo frame.
Help people export their photos for printing. Only offer this service for a person's personal and non-commercial use.
Access photos for use in a way that visibly enhances the in-app experience (e.g. photo editing, collage, slideshow, and face-in-hole apps).
Access a person's previous profile pictures.
Create albums on behalf of user (posting pictures requires the publish_actions permission.)
user_posts
Provides access to the posts on a person's Timeline. Includes their own posts, posts they are tagged in, and posts other people make on their Timeline.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Provide creative content from Timeline posts.
Provide value to the user by visibly analyzing the content of the posts on their Timeline.
Non-visible use of this data such as sentiment analysis or guarding against spam bots.
user_relationships
Provides access to a person's relationship status, significant other and family members as fields on the User object.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Surface content of relevance to relationship connections. For example, showing a Father's specific content related to being a Dad.
Reduce friction in utility apps that require relationship information such as Family Tree apps.
user_relationship_details
Provides access to a person's relationship interests as the interested_in field on the User object.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Provide tailored content to people based on their 'interested in' details.
user_religion_politics
Provides access to a person's religious and political affiliations.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Surface content relevant to beliefs or political association.
Optimize connections with others based on similar interests.
user_status
This permission is only available for apps using Graph API version v2.3 or older.
If you are calling the endpoint /{user-id}/posts or /{user-id}/feed, ask for the user_posts permission instead (only v2.3 or older).
Provides access to a person's statuses. These are posts on Facebook which don't include links, videos or photos.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Provide creative content from status updates.
Provide value to the user by visibly analyzing the content of their past statuses.
Non-visible use of this data such as sentiment analysis or guarding against spam bots.
user_tagged_places
Provides access to the Places a person has been tagged at in photos, videos, statuses and links.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Provide tailored content based on the places a person has been.
Recommend places to visit based on the places a person has previously been tagged at.
Show someone their checkin history on a map.
user_videos
Provides access to the videos a person has uploaded or been tagged in.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Access videos for use videos in a way that visibly enhances the in-app experience: (e.g. editing, collage, portfolio, slideshow apps.)
Display a person's videos on a TV via a set top box, or display their videos on a digital photo frame.
user_website
Provides access to the person's personal website URL via the website field on the User object.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Reduce friction in portfolio, resume or business apps that use personal website information.
user_work_history
Provides access to a person's work history and list of employers via the work field on the User object.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Surface content of relevance based on industry, job title or similar.
Help people connect with others based on a common work history.
Analytics purposes that are not clearly visible in app.
Extended Permissions
Extended Permissions give access to more sensitive information and give your app the ability to publish and delete data. All extended permissions appear on a separate screen during the login flow so a person can decide if they want to grant them.
read_custom_friendlists
Provides access to the names of custom lists a person has created to organize their friends. This is useful for rendering an audience selector when someone is publishing stories to Facebook from your app.
This permission does not give access to a list of person's friends. If you want to access a person's friends who also use your app, you should use the user_friends permission.
This permission will also not help you invite a person's friends to use your app. To learn more about how to invite friends to an app, please see our FAQs.
This permission also does not give the list of friends who are part of a friendlist. It only gives access to the names of the lists.
This permission was called read_friendlists before v2.3.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Build a custom audience selector to let people choose who sees a particular story published by your app.
read_insights
Provides read-only access to the Insights data for Pages, Apps and web domains the person owns.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Integrate Facebook's app, page or domain insights into your own analytics tools.
Transfer or sell insights data to third parties.
Provide any non-visible use of insights.
read_audience_network_insights
Provides read-only access to the Audience Network Insights data for Apps the person owns.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Integrate Facebook's app Audience Network insights into your own analytics tools.
Transfer or sell insights data to third parties.
Provide any non-visible use of insights.
read_mailbox
This permission is only available for apps using Graph API version v2.3 or older.
Provides the ability to read the messages in a person's Facebook Inbox through the inbox edge and the thread node.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Limited Use
This permission is granted to apps building a Facebook-branded client on platforms where Facebook is not already available. For example, Android and iOS apps will not be approved for this permission. In addition, Web, Desktop, in-car and TV apps will not be granted this permission.
read_page_mailboxes
Provides the ability to read from the Page Inboxes of the Pages managed by a person. This permission is often used alongside the manage_pages permission.
This permission does not let your app read the page owner's mailbox. It only applies to the page's mailbox.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Let someone manage the mailboxes of their Pages through your app.
read_stream
This permission is only available for apps using Graph API version v2.3 or older. See user_posts as a possible alternative.
Provides access to read the posts in a person's News Feed, or the posts on their Profile.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Limited Use
This permission is granted to apps building a Facebook-branded client on platforms where Facebook is not already available. For example, Android and iOS apps will not be approved for this permission. In addition, Web, Desktop, in-car and TV apps will not be granted this permission.
manage_notifications
This permission is only available for apps using Graph API version v2.3 or older.
Enables your app to read a person's notifications and mark them as read.
This permission does not let you send notifications to a person.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Limited Use
This permission is granted to apps building a Facebook-branded client on platforms where Facebook is not already available. For example, Android and iOS apps will not be approved for this permission. In addition, Web, Desktop, in-car and TV apps will not be granted this permission.
manage_pages
Enables your app to retrieve Page Access Tokens for the Pages and Apps that the person administrates.
Apps need both manage_pages and publish_pages to be able to publish as a Page.
Review
If your app requests this permission Facebook will have to review how your app uses it. You can grant this permission on behalf of people listed within the Roles section of your App's Dashboard without review by Facebook.
When submitting for review, please make sure your instructions are easily reproducible by our team. For example, if your Page Management Tool has its own authentication system, please ensure you provide a working login (such as a username/password) to allow our review team to use your tool and test this functionality.
Common Usage
Publish content to Pages owned by the people who use your app. Publishing also requires the publish_pages permission.
Help people manage the posts, comments and likes published to their Pages.
publish_pages
When you also have the manage_pages permission, gives your app the ability to post, comment and like as any of the Pages managed by a person using your app.
Apps need both manage_pages and publish_pages to be able to publish as a Page.
Publishing as an individual personal account is not possible with this permission. To post as an individual, please see the publish_actions permission.
Review
If your app requests this permission Facebook will have to review how your app uses it.
When requesting this permission via App Review, please make sure your instructions are easily reproducible by our team.
Common Usage
Let people explicitly publish content from your app to any of the Facebook Pages they manage from within a custom composer.
Seamlessly like and comment on behalf of the Pages a person manages.
Automatically publish stories without the person being aware or having control.
Pre-fill the message parameter of posts with content a person or business didn’t create, even if the page admin can edit or remove the content before sharing.
publish_actions
Provides access to publish Posts, Open Graph actions, achievements, scores and other activity on behalf of a person using your app.
Because this permission lets you publish on behalf of a user please read the Platform Policies to ensure you understand how to properly use this permission.
Your app does not need to request the publish_actions permission in order to use the Feed Dialog, the Requests Dialog or the Send Dialog
Review
If your app requests this permission Facebook will have to review how your app uses it.
When requesting this permission via App Review, please make sure your instructions are easily reproducible by our team.
Common Usage
Let people explicitly publish content from your app to Facebook from within a custom composer.
Seamlessly publish Open Graph stories for people when the user is aware and has appropriate controls.
Automatically publish stories without the person being aware or having control.
Publishing via dialogs or social plugins does not require this permission. Do not request review of this permission if you're only using Share dialog, Feed Dialog, Message Dialog etc, or Social Plugins (e.g. the Like Button.)
Pre-fill the user message parameter of posts with content a person didn’t create, even if the person can edit or remove the content before sharing.
Gate access to a service or product, or incentivize sharing to the user, group or event timeline.
rsvp_event
Provides the ability to set a person's attendee status on Facebook Events (e.g. attending, maybe, or declined).
This permission does not let you invite people to an event.
This permission does not let you update an event's details.
This permission does not let you create an event. There is no way to create an event through the API.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Reduce friction for people in managing events and calendar information (e.g. device apps, planner apps, concert apps.)
pages_show_list
Provides the access to show the list of the Pages that you manage.
Common Usage
Provides API access to your accounts for showing the list of the Pages that you manage
pages_manage_cta
Provides the access to manage call to actions of the Pages that you manage.
Review
Your app may use this permission without review from Facebook.
Common Usage
Provides API access to manage call to actions of the Pages that you manage
pages_manage_instant_articles
Lets your app manage Instant Articles on behalf of Facebook Pages administered by people using your app.
Review
If your app requests this permission Facebook will have to review how your app uses it. You can grant this permission on behalf of people listed within the Roles section of your app dashboard without needing review by Facebook.
If you want to use the Instant Articles Plugin for WordPress (or a similar tool) to publish blog posts as Instant Articles, you do not need to submit for review as long as all those for whom you want to publish are listed in the Roles section of your app dashboard.
When you submit for review, please make sure your instructions are easily reproducible by our team. For example, if your app has its own authentication system, please provide a working login information (such as a username/password) to allow our review team to use your tool and test this functionality.
Common Usage
Create and update Instant Articles for Pages owned by the people who use your app.
ads_read
Provides the access to Ads Insights API to pull ads report information for ad accounts you have access to.
This permission does not let you update purchase, update, or otherwise modify ads.
Common Usage
Provides API access to your ad performance data for use in custom dashboards and data analytics
ads_management
Provides the ability to both read and manage the ads for ad accounts you have access to. Please see Ads Management for details.
Common Usage
Programmatically create campaigns, manage ads , and fetch metrics
Build ad management tools that provide innovative solutions and differentiated value for advertisers
business_management
Read and write with Business Management API
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Manage business assets such as an ad account. Claiming ad accounts.
Performing general page management and administration only.
pages_messaging (Send/Receive API)
This allows you to send and receive messages through a Facebook Page, but only within 24h hours after a user action. For post 24h messages see the next permission. Conversations through this API can only begin when someone indicates—through a Messenger plugin or directly messaging you—that they want to receive messages from you.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Creating user-initiated interactive experiences
Confirming bookings, purchases, orders, etc.
Sending customer support messages
Messaging people without their consent
pages_messaging_subscriptions (Send/Receive API)
This allows you to send and receive messages through a Facebook Page out of the 24h window opened by a user action. This permission cannot be used to send promotional or advertising content.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Sending news
Sending productivity updates
Sending personal tracking notifications
Up-selling or cross-selling products or services
Sending brand advertising, newsletters, announcements or spam
pages_messaging_payments (Send/Receive API)
This allows you to charge users in Messenger conversations on behalf of pages. Intended for tangible goods only, not virtual or subscriptions.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Selling products
Selling tickets
Hotel bookings and car rentals
Selling virtual currency
Subscribing to content updates
pages_messaging_phone_number (Customer Matching)
This allows you to send and receive messages through a Facebook Page. This permission cannot be used to send promotional or advertising content. Conversations through this API can only begin when someone indicates—through a Messenger plugin or directly messaging you—that they want to receive messages from you.
Review
If your app requests this permission Facebook will have to review how your app uses it.
Common Usage
Sending content you'd normally send through SMS
Messaging people without their consent