Extended permissions
From Facebook Developer Wiki
Facebook offers some API functionality that requires the user to specifically opt in before your application or site can use that functionality. These methods are specific to certain use cases that require a greater level of trust from the user. Users express this trust by granting your application or site specific extended permissions. These permissions allow your application to perform certain actions.
You can also prompt a user who administers a Facebook Page to grant permissions for the Page as well. If the user is a Page admin and encounters the permission dialog, the user can choose to whom the permission applies: to the user him or herself and to any or all of the Pages.
The available extended permissions are:
| Permission | Description |
|---|---|
| publish_stream | Lets your application or site post content, comments, and likes to a user's profile and in the streams of the user's friends without prompting the user.
This permission is a superset of the status_update, photo_upload, video_upload, create_note, and share_item extended permissions, so if you haven't prompted users for those permissions yet, you need only prompt them for publish_stream. |
| read_stream | Lets your application or site access a user's stream and display it. This includes all of the posts in a user's stream. You need an active session with the user to get this data. |
| This permission allows an application to send email to its user. This permission can be obtained only through the fb:prompt-permission tag or the promptpermission attribute. When the user accepts, you can send him/her an email via notifications.sendEmail or directly to the proxied_email FQL field. | |
| read_mailbox | This permission grants an application the ability to read from a user's Facebook Inbox. You can read from a user's Inbox via message.getThreadsInFolder as well as the mailbox_folder, thread, and message FQL tables. |
| offline_access | This permission grants an application access to user data when the user is offline or doesn't have an active session. This permission can be obtained only through the fb:prompt-permission tag or the promptpermission attribute. Read more about session keys. |
| create_event | This permission allows an app to create and modify events for a user via the events.create, events.edit and events.cancel methods. |
| rsvp_event | This permission allows an app to RSVP to an event on behalf of a user via the events.rsvp method. |
| sms | This permission allows a mobile application to send messages to the user and respond to messages from the user via text message. |
| status_update | This permission grants your application the ability to update a user's or Facebook Page's status with the status.set or users.setStatus method.
Note: You should prompt users for the publish_stream permission instead, since it includes the ability to update a user's status. |
| photo_upload | This permission relaxes requirements on the photos.upload and photos.addTag methods. If the user grants this permission, photos uploaded by the application will bypass the pending state and the user will not have to manually approve the photos each time.
Note: You should prompt users for the publish_stream permission instead, since it includes the ability to upload a photo. |
| video_upload | This permission allows an application to provide the mechanism for a user to upload videos to their profile.
Note: You should prompt users for the publish_stream permission instead, since it includes the ability to upload a video. |
| create_note | This permission allows an application to provide the mechanism for a user to write, edit, and delete notes on their profile.
Note: You should prompt users for the publish_stream permission instead, since it includes the ability to let a user write notes. |
| share_item | This permission allows an application to provide the mechanism for a user to post links to their profile.
Note: You should prompt users for the publish_stream permission instead, since it includes the ability to let a user share links. |
You can query whether a user has granted your application or site any of the above permissions using the users.hasAppPermission method or the permissions FQL table.
[edit] Granting Extended Permission
You must prompt your users to grant extended permissions. You can request one or more extended permissions from a user using one of these methods:
- By including the fb:prompt-permission tag in your FBML application. For example:
- <fb:prompt-permission perms="read_stream,publish_stream"> Grant permission for status updates </fb:prompt-permission>
- By calling Facebook.showPermissionDialog, for use with FBJS and FBML applications. Use this method to prompt for any permission from a Facebook Page.
- By calling FB.Connect.showPermissionDialog, for use with IFrame applications and Facebook Connect sites. For Facebook Pages, you can prompt only for the
publish_streampermission using this method. - By including the promptpermission attribute in a form. You can't use the
promptpermissionattribute for Connect sites and IFrame applications. - By directing them to the URL: http://www.facebook.com/connect/prompt_permissions.php. Desktop applications can use this method only to prompt for permissions. For information on formatting this URL, read Authorization and Authentication for Desktop Applications.
- For mobile applications, by directing the user to the URL: http://m.facebook.com/authorize.php?api_key=YOUR_API_KEY&v=1.0&ext_perm=PERMISSION_NAME
When the user submits the form or follows the URL, a permissions dialog like the following appears. The user is prompted for each permission in a separate dialog.
[edit] Revoking Extended Permissions
If you need to revoke an extended permission from a user, call auth.revokeExtendedPermission.
Should a user want to revoke an extended permission, direct the user to the URL: http://www.facebook.com/editapps.php.
Users can reach this page by clicking Edit Applications in the applications menu (or choosing Settings > Application Settings on the top menubar, then click Edit Settings next to the application in question. On the Additional Permissions tab, the user can revoke the extended permission there.
There is no direct URL for editing the permissions for a single application. Users have to click the appropriate application's Edit Settings link on the Edit Applications page.
