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 the`education` 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 the`notes` 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`, or`friends_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 `work`property
`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.