Authentication

Both Graph API and Marketing API calls require an access token to be passed as a parameter in each API call. In this guide, we teach you how to get access tokens for testing purposes.

To learn more about authentication, see our main documentation:

Graph API Explorer

You can get a test user access token with Graph API Explorer. To learn how to use the explorer, see Graph API Explorer Guide.

Obtain User Access Token

  1. Go to Graph API Explorer.
  2. In Facebook App, select an app used to obtain the access token.
  3. In User or Page, select User Token.
  4. Under Permissions, check ads_read.
  5. Click Generate Access Token. The box on top of the button is populated with the access token.
  6. Store that token for later use.

Debug

To get more information in the token you just generated, click on the i button shown before the token. After the click, a pop-up screen opens and displays some basic information about the token. Click on Open in Access Token Tool to be redirected to the Access Token Debugger.

You can also directly access the Access Token Debugger and paste the token you generated in the text box.

While debugging, check:

  • App ID: The app ID mentioned in the prerequisite section.
  • Expires: A time stamp. A short-lived token expires in an hour or two
  • Scopes: Contains the permissions added on Graph API Explorer.

Extend Access Token

  1. Complete all steps to obtain the access token using the Graph API Explorer.
  2. Copy your token. Paste it in the text box on the Access Token Debugger.
  3. On the Access Token Debugger, scroll all the way down to the bottom of the page.
  4. Click Extend Access Token to get a long-lived token. Copy that token for later use.

Check your new token’s properties using the Access Token Debugger. It should have a longer expiration time, such as 60 days, or Never under Expires. See Long-Lived Access Token.

Get token manually

If the user clicks the Allow button when you prompt for the extended permissions, the user is redirected to a URL that contains the value of the redirect_uri parameter and an authorization code:

http://YOUR_URL?code=<AUTHORIZATION_CODE>

Build a URL that includes the endpoint for getting a token, your app ID, your site URL, your app secret, and the authorization code you just received. The URL will be similar to the following:

https://graph.facebook.com/<API_VERSION>/oauth/access_token?
  client_id=<YOUR_APP_ID>
  &redirect_uri=<YOUR_URL>
  &client_secret=<YOUR_APP_SECRET>
  &code=<AUTHORIZATION_CODE>

The response should contain the access token for the user:

  • If you follow the server-side authentication flow, you get a persistent token.
  • If you follow the client-side authentication flow, you get a token with a finite validity period of about one to two hours. This can be exchanged for a persistent token by calling the Graph API endpoint for Extending Tokens.

If the API is to be invoked by a System User of a business, you can use a System User Access Token.

You can debug the access token, check for expiration, and validate the permissions granted using the access token debugger or the programmatic validation API.

Store Token

The token should be stored in your database for subsequent API calls. You should regularly check for validity of the token, and if necessary prompt the user for permission. Even a persistent token can become invalid in a few cases including the following:

  • The user’s password changes
  • The user revokes permissions

As access tokens can be invalidated or revoked anytime, your app should expect to have a flow to re-request permission from the user. When a user starts your web app, check the validity of the token you have for that user. If necessary, send them through the authentication flow to get an updated token.

If this is not possible for your app, you may need a different way to prompt the user. This can happen in cases where the API calls are not directly triggered by a user interface, or are made by periodically run scripts. A possible solutions is to send users an email with instructions.