Removal of offline_access permission

Access_tokens allow users to interact with your apps in secure and social ways. While we are removing the use of the offline_access permission, through a migration setting in the App Dashboard, we are now allowing the option to use access_tokens with a long-lived expiration time that can be renewed each time the user revisits your app (see exceptions below). For existing apps that are not using the offline_access permission, there are no changes required for your app, but you should consider using the new endpoint that allows the longer expiration time.

Extending the expiration of existing short-lived user access_tokens

When a user visits your site with an existing, valid, short-lived user access_token, you have the option to extend the expiration time of that access token. Our platform will only extend the expiration time once per day, so even if a user revisits your site multiple times a day, the token will be extended the first time requested. You must make sure to call the new endpoint below before the short-lived access_token expires. Currently the long-lived user access_token will be valid for 60 days while the short-lived user access_tokens are currently valid from 1 to 2 hours.

Some Exceptions

Exception 1: Desktop Apps

Once the migration setting has been enabled, Desktop applications will automatically get user access_tokens returned that have the longer expiration time. However, there is no way to get a long-lived user access_token without having the user login to your app again.

Exception 2: Native Mobile Apps using older SDKs (iOS and Android)

We released an update to our SDKs for iPhone and Android that will allow access_token expiration to be extended. If you continue to use an older version, and do not implement changes to extend the token, the user will have to re-login to your app periodically when the access_token expires. See the iOS and Android doc pages for more information:

Exception 3: Native Mobile Apps using newer SDKs (iOS and Android)

Once the migration setting has been enabled, mobile applications using our newer SDKs will automatically be granted a user access_token with the longer expiration, you do not have to do anything to get this extended. Also, each day a user revisits your app, you will be granted a new user access_token with a fresh expiration time. Note: Each day, the access_token returned may or may not be the same access_token as the previous day.

Exception 4: Ads APIs

Ads APIs are special cased to allow collection of statistics offline. PMD partners should use server-side OAuth flow in order to receive a non-expiring token rather than a token that has longer expiration time.

Getting started with the new migration setting

You will see a new migration called "deprecate offline_access" in your Advanced settings of the App Dashboard. Enable it and click "Save Changes" for the migration to take effect for that app. After the migration is enabled, apps can create and extend access tokens under the new token model. Additionally, if you were previously requesting the offline_access permission, that permission will no longer be displayed in the Login Dialog to new users.

Scenario 1: If you were NOT previously asking for offline_access

There are no required changes needed for your app to continue functioning. If you were obtaining user access_tokens through the signed_requests or those returned in a browser hash-tag (client-side), those tokens will have short expirations. You should consider using our new endpoint to exchange them for new access_tokens that have a longer expiration time. When you do the exchange, your short-lived access_token will continue to function until it expires, however, the new endpoint will return a second access_token that will have a much longer expiration and this is what you should use going forward.

Scenario 2: If you have been previously requesting offline_access - updated 4/30/2012

Once the migration has been enabled, existing use access_tokens, with the offline_access permission, will continue to work without any change to their expiration time. However, new users to your app will not be prompted for the offline_access permission in the Login Dialog and will receive either a short-lived or long-lived access_token depending on your environment and how you are requesting the access_token (client or server-side OAuth, see Scenario 3 and 4 below).

After the offline_access removal date (see roadmap for exact date), all existing offline_access access_tokens will have their expiration time truncated to 60 days. This truncation will be transparent to the user and your app will continue functioning normally; Facebook will send an updated message through the weekly developer round-up when this truncation will occur.

Scenario 3: Server-side OAuth Developers

Once the migration is enabled, if the access_token is generated from a server-side OAuth call, the resulting access_token will have the longer expiration time by default. If the call is made while there is still a valid long-lived user access_token for that user, the returned user access_token from this second call may be the same or may have changed, but in either case the expiration time will be set to a long expiration time.
Note: The user must access your application before you're able to get a valid "authorization Code" to be able to make the server-side OAuth call again. Apps will not be able to setup a background/cron job that tries to automatically extend the expiration time, because the "authorization code" is short-lived and will have expired.

Scenario 4: Client-side OAuth and Extending Access_Token Expiration Time through New Endpoint

Using the new endpoint below, you will be able to extend the expiration time of an existing, non-expired, short-lived user access_token. Please note, the endpoint can only be used to extend the short-lived user access_tokens. If you pass an access_token that had a long-lived expiration time, the endpoint will simply pass that same access_token back to you without altering or extending the expiration time.

To get the long-lived user access_token simply pass your own client_id (your app_id), your app_secret, and the non-expired, short-lived access_token to the endpoint below. You will be returned a new long-lived user access_token; this access_token will exist in addition to the short-lived access_token that was passed into the endpoint. If you would like to refresh a still valid long-lived access_token, you will have to get a new short-lived user access_token first and then call the same endpoint below. The returned access_token will have a fresh long-lived expiration time, however, the access_token itself may or may not be the same as the previously granted long-lived access_token.

https://graph.facebook.com/oauth/access_token?             
    client_id=APP_ID&
    client_secret=APP_SECRET&
    grant_type=fb_exchange_token&
    fb_exchange_token=EXISTING_ACCESS_TOKEN

Scenario 5: Page Access Tokens

When a user grants an app the manage_pages permission, the app is able to obtain page access tokens for pages that the user administers by querying the [User ID]/accounts Graph API endpoint. With the migration enabled, when using a short-lived user access token to query this endpoint, the page access tokens obtained are short-lived as well.

Exchange the short-lived user access token for a long-lived access token using the endpoint and steps explained earlier. By using a long-lived user access token, querying the [User ID]/accounts endpoint will now provide page access tokens that do not expire for pages that a user manages. This will also apply when querying with a non-expiring user access token obtained through the deprecated offline_access permission.

Handling expired tokens, user password changes, uninstalled apps, and user logout

Regardless if your app requested the offline_access permission, apps should gracefully handle an expired access tokens in situations where a user changes their password, deauthorizes an app, or logs out. More information on these cases including a simple code solution that leads to a uniform user experience can be found in this blog post.

We're excited for this new migration and know that it will be great for both developers and users. We look forward to seeing your great applications as we continue to give you the tools and features that help you build and innovate on the Facebook platform.

Updated about 3 weeks ago