Facebook Graph Access Token Requirements

I apologize for the lack of any blog updates this past month. My available time to write this summer has not been significant.

FacebookAs is the innate nature of third party platforms, one's reliance on public APIs for use in their own projects is subject to change and can break at any time. One such breaking change for a slew of sites and scripts, one of mine included, happened recently via Facebook Graph.  Facebook Graph provides a simplified means of communicating between Facebook and external sources including websites and applications.

A practical and simple use for Facebook Graph is to retrieve and embed Facebook photos and posts into external websites.  I had implemented such capabilities for an organization last year so that the organization's staff could easily upload new albums of photos to their public Facebook page, whereby those images would be dynamically pulled into their official website without any redundant work or technical know-how required.

Until June, there was but one requirement for retrieving a list of images from a public photo album on a Facebook page and embedding them on an external site.  All a person needed to know was the album ID itself, then metadata pertaining to the album's images could be retrieved via a simple Facebook Graph call.  As an example, to retrieve the images posted to Facebook's own "Facebook Foxes" album you could just  call the URL:

https://graph.facebook.com/10152716010956729/photos?fields=source,picture,link,name

Until Facebook's recent changes, the URL above would return a JSON response containing details of each image in the specified album. There are many other fields that can be specified in the URL to return additional photo data, as outlined by Facebook Graph's documentation.

In June, Facebook began requiring access tokens for even the most basic read-only data calls using Facebook Graph.  As a consequence, scripts that made non-authenticated calls to Facebook Graph in a manner similar to the above were suddenly only served the following as return data:

This has broken a lot of publicly shared scripts for jQuery, PHP etc. that did not initially implement access tokens.  The basic solution is easy enough—generate an access token by defining a new bare-bones 'Application' through Facebook's developer portal, and include that token as another parameter ["access_token"] in the URL call. I'll briefly walk through that process here.

Creating a Facebook Application

In order to obtain the required access token for Facebook Graph data communications, you have to define a new application through Facebook's website. As we are just looking to get the access token, this is a quick process:

  1. Login to Facebook and visit your App Dashboard via: https://developers.facebook.com/apps/.
  2. Click on the green "Add a New App" button.
  3. In this demo, I am calling Facebook Graph via a website, so select "Website" for the Platform.
  4. Enter the name of your app (i.e., the name of the website itself) then click "Create New Facebook App ID"
  5. Choose a category and then click "Create App ID".
Facebook

Creating a basic Website application to retrieve access token.

Since the application in this particular example is merely to retrieve the access token, no additional information is required and you can now click "Skip Quick Start" at the top-right.  However, you can also use this application entity as an entrance point for any Facebook-driven website application and can include additional information about the app at this time or in the future, so feel free to continue with the quick start as you wish. By default the application entry is in developer mode and not publicly available. This is sufficient for the read-only use case described in this post but for any more complex application-like uses you'll want to check out the "Status & Review" section of the app's page to make the application publicly available and so forth.

Retrieving the Access Token

Now that we've created a dummy application for basic Facebook Graph website interactions, you can retrieve the access token as follows:

  1. Login to Facebook and visit your App Dashboard via: https://developers.facebook.com/apps/.
  2. Click on the application you just created to be taken to its own dashboard page.
  3. You will see the App ID listed, and should click "Show" to reveal the App Secret.
  4. Copy the URL below, replacing APP_ID and APP_SECRET with the values retrieved above:
    1. https://graph.facebook.com/oauth/access_token?client_id=APP_ID&client_secret=APP_SECRET&grant_type=client_credentials
Facebook

Click on 'Show' to reveal your App Secret. The App ID and App Secret are used to retrieve the Access Token.

If all of the steps above have been performed correctly, the data returned from the URL above will appear similar to:

access_token=###############|###########################

Now it is a matter of including that access_token parameter and value in the query string of the original Facebook Graph request. In the original example used here, the modified URL would become:

https://graph.facebook.com/10152716010956729/photos?fields=source,picture,link,name&access_token=###############|###########################

With all of this in place, the JSON response should be valid and will contain the requested data. This information can then be parsed and acted upon from the external website script. The returned data in the example above, once a valid access token is specified, is depicted below:

I should add that a photo album's ID can be determined by accessing the album via Facebook and reviewing the URL.  A sample URL when viewing a photo album is: https://www.facebook.com/media/set/?set=a.10152716010956729.1073741827.20531316728&type=3.  The bold numerical value (between the first two decimal points) corresponds to the album ID; this is what you would pass via Facebook Graph to retrieve the image data.

Note: Since the access token is sent to Facebook Graph as plain text and is often embedded within client-side code, it is easy for others to steal your app's access token and use it for their own Facebook Graph calls, often with malicious intent. There are additional steps you can take to better secure your access token and app, as described in this Facebook post titled Securing Graph API Requests.