Authentication

Please note: On May 2, 2012, the offline_access permission will be removed. If you are building a new application you shouldn't use this permission. Instead please check the Deprecation of Offline Access Permission document which explains how to start using access tokens that are valid for up to 60 days.

Authentication gives your app the ability to know the identity of a Facebook user, and to read and write data via Facebook's APIs. The Facebook Platform uses OAuth 2.0 for authentication and authorization.

A successful authentication flow results in your application obtaining a user access token which can be used to make requests to Facebook's APIs. There are several authentication flows - each is applicable to a different platform or context:

• Authentication in native Android apps
• Authentication in native iOS apps
• Authentication within a Page Tab on www.facebook.com
• Authentication within a Canvas Page on apps.facebook.com
• Authentication for Websites & Mobile Web apps using Javascript (client-side flow)
• Authentication for Websites & Mobile Web apps using a Server (server-side flow)
• Authentication for devices without access to a browser

In addition to obtaining User access tokens, it's possible to obtain App access tokens and Page access tokens. App and Page access tokens allow you to use the Graph API on behalf of an App or a Page in order to modify your application's properties, create test users or to read Insights data for example.

Permissions

By default, when authorizing your application, a user only grants your app access to their basic information. If you want to read additional data or write data to Facebook, you need to request additional permissions. In the various authentication flows, you should specify the additional permissions you require using the scope parameter.
To see which additional permissions you can request, and the access they offer you, see the Permissions reference.
It's possible to programmatically check which permissions a user has granted your application by performing an HTTP GET on:

https://graph.facebook.com/me/permissions?
    access_token=USER_ACCESS_TOKEN

Its also possible to programmatically revoke a permission which a user has previously granted your application by performing an HTTP DELETE on:

https://graph.facebook.com/me/permissions/PERMISSION_NAME?
    access_token=USER_ACCESS_TOKEN

Access Token Validity & Expiration

When you obtain an access token from Facebook, it will be valid immediately and usable in requests to the API for some time period defined by Facebook. After that period has elapsed, the access token is considered to have expired and the user will need to be authenticated again in order for your app to obtain a fresh access token. The duration for which a given access token is valid depends on how it was generated.
There are also events which may cause an access token to become invalid before its expected expiry time. Such events include the user changing their password, an application refreshing it's App Secret. Dealing with varying access token expiry times, and handling the case when an access token becomes invalid before its expected expiry time is essential for building robust social experiences.
See how to Handle Invalid and Expired access tokens.

Application De-authorization

When a user removes your app in their account settings or blocks the app in the News Feed, you can be notified by specifying a value for the Deauthorize Callback URL property in your app's settings.
Upon app removal we will send an HTTP POST request containing a single parameter, signed_request, which, once decoded, will yield a JSON object containing the user_id of the user who just deauthorized your app. You will not receive an user access token in this request and all existing user access tokens that were previously issues on behalf of that user will become invalid.
Upon receiving this request, you can perform any cleanup scripts which, for example, remove that user's personal information from your servers.

Logging the user out of Facebook

You can programmatically log the user our of Facebook by redirecting the user to

https://www.facebook.com/logout.php?
    next=YOUR_REDIRECT_URL
   &access_token=USER_ACCESS_TOKEN

The URL supplied in the next parameter must be a URL with the same base domain as your application as defined in your app's settings.
You can also log the user out of Facebook on the client-side using the Javascript SDK by calling FB.logout().

Windows, OS X and Linux native apps

Our OAuth 2.0 implementation does not include explicit support for application built for desktop operating systems. However, if your app can embed a web browser (most desktop frameworks such as .NET, AIR and Cocoa support embedding browsers), you can use the client-side flow with one modification: a specific redirect_uri. Rather than requiring desktop apps to host a web server and populate the Site URL in the App Dashboard, we provide a specific URL you can use with desktop apps: https://www.facebook.com/connect/login_success.html.

1. Embed a web browser and implement the client-side authentication flow:

https://www.facebook.com/dialog/oauth?
    client_id=YOUR_APP_ID
   &redirect_uri=https://www.facebook.com/connect/login_success.html
   &response_type=token

2. After the user authorizes your app, Facebook will redirect the user to that URL and pass an the access token in the URI fragment:

https://www.facebook.com/connect/login_success.html#
    access_token=USER_ACCESS_TOKEN

You should detect this redirect and then read the access token out of the URI using whatever mechanisms provided by your OS and development framework of choice.