Facebook Permissions

This document discusses the various types of permissions that your app can request the user which enable your app to either read or write certain information on the user’s behalf. To learn more about how to access these permissions for a user, please read ourauthentication documentation.

Important Terms

When referring to access tokens and permissions in our documentation, we use the following terms to describe the kinds of tokens and permissions you need to perform particular operations:

Publicly available

No access_token or permission is required.

Any valid access_token

Any valid access token returned by our APIs. An access token may not be valid if, for example, it has expired. No special permissions are required. Occasionally, this is referred to as a generic access_token.

App access_token

An access token for an application. This is obtained by authenticating the application with the APP_ID and APP_SECRET, as described under App Login in Authentication page.

User access_token

An access_token for a user, with no special permissions required. This is the access token returned by the Client-side and Server-side authentication flows.

Page access_token

An access_token used to manage a page. This is used when you want to perform an operation acting as a Page. This access token is retrieved by issuing an HTTP GET to /USER_ID/accounts or to /PAGE_ID?fields=access_token with themanage_pages permission. Getting /USER_ID/accounts will return a list of Pages (including app profile pages) to which the user has administrative access in addition to an access_token for each Page. Alternatively, you can get a page access token for a single, specific, page by issuing an HTTP GET to /PAGE_ID?fields=access_token with the manage_pages permission (you must ask for the access_token field specifically via the fields= parameter). See the documentation for the Page object for more information. NOTE: After September 22, 2011, manage_pages permission will be required for all access to a user’s pages via this connection, i.e. for both reading the user’s pages and also retrieving access_tokens for those pages. See the documentation for the User object for more information.

A specific permission

A permission, from the list below, that is required to perform a particular operation. For example user_checkins is required to read a user’s checkins.

In many cases, you can perform an operation without a specific permission, but can retrieve more information (or perform additional operations) with a specific permission. In these cases, we will list the complete set of permissions, such as: ‘any validaccess_token or user_groups‘.

User and friends Permissions

The set of permissions below basically explain what types of permissions you can ask a user in the scope parameter of your auth dialog to get the permissions you need for your app.

User permission Friends permission Description
user_about_me friends_about_me Provides access to the “About Me” section of the profile in the about property
user_activities friends_activities Provides access to the user’s list of activities as the activities connection
user_birthday friends_birthday Provides access to the birthday with year as the birthday_date property
user_checkins friends_checkins Provides read access to the authorized user’s check-ins or a friend’s check-ins that the user can see.
user_education_history friends_education_history Provides access to education history as theeducation property
user_events friends_events Provides access to the list of events the user is attending as the events connection
user_groups friends_groups Provides access to the list of groups the user is a member of as the groups connection
user_hometown friends_hometown Provides access to the user’s hometown in the hometown property
user_interests friends_interests Provides access to the user’s list of interests as the interests connection
user_likes friends_likes Provides access to the list of all of the pages the user has liked as the likes connection
user_location friends_location Provides access to the user’s current location as the location property
user_notes friends_notes Provides access to the user’s notes as thenotes connection
user_online_presence friends_online_presence Provides access to the user’s online/offline presence
user_photo_video_tags friends_photo_video_tags Deprecated; not supported after November 22, 2011. Provides access to the photos and videos the user has uploaded, and photos and videos the user has been tagged in; this permission is equivalent to requesting both user_photos and user_videos, orfriends_photos and friends_videos.
user_photos friends_photos Provides access to the photos the user has uploaded, and photos the user has been tagged in
user_relationships friends_relationships Provides access to the user’s family and personal relationships and relationship status
user_relationship_details friends_relationship_details Provides access to the user’s relationship preferences
user_religion_politics friends_religion_politics Provides access to the user’s religious and political affiliations
user_status friends_status Provides access to the user’s most recent status message
user_videos friends_videos Provides access to the videos the user has uploaded, and videos the user has been tagged in
user_website friends_website Provides access to the user’s web site URL
user_work_history friends_work_history Provides access to work history as the workproperty
email N/A Provides access to the user’s primary email address in the email property. Do not spam users. Your use of email must comply both with Facebook policies and with the CAN-SPAM Act.

Extended Permissions

Permission Description
read_friendlists Provides access to any friend lists the user created. All user’s friends are provided as part of basic data, this extended permission grants access to the lists of friends a user has created, and should only be requested if your application utilizes lists of friends.
read_insights Provides read access to the Insights data for pages, applications, and domains the user owns.
read_mailbox Provides the ability to read from a user’s Facebook Inbox.
read_requests Provides read access to the user’s friend requests
read_stream Provides access to all the posts in the user’s News Feed and enables your application to perform searches against the user’s News Feed
xmpp_login Provides applications that integrate with Facebook Chat the ability to log in users.
ads_management Provides the ability to manage ads and call the Facebook Ads API on behalf of a user.
create_event Enables your application to create and modify events on the user’s behalf
manage_friendlists Enables your app to create and edit the user’s friend lists.
manage_notifications Enables your app to read notifications and mark them as read. This permission will be required to all access to notifications after October 22, 2011.
offline_access Enables your app to perform authorized requests on behalf of the user at any time. By default, most access tokens expire after a short time period to ensure applications only make requests on behalf of the user when the are actively using the application. This permission makes the access token returned by our OAuth endpoint long-lived.
publish_checkins Enables your app to perform checkins on behalf of the user.
publish_stream Enables your app to post content, comments, and likes to a user’s stream and to the streams of the user’s friends. With this permission, you can publish content to a user’s feed at any time, without requiring offline_access. However, please note that Facebook recommends a user-initiated sharing model.
rsvp_event Enables your application to RSVP to events on the user’s behalf
sms Enables your application to send messages to the user and respond to messages from the user via text message
publish_actions Enables your application to publish user scores and achievements.

Page Permissions

Permission Description
manage_pages Enables your application to retrieve access_tokens for pages the user administrates. The access tokens can be queried using the “accounts” connection in the Graph API. This permission is only compatible with the Graph API.

Leave a comment