Marketing API

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: Access Tokens for Meta Technologies

This documentation will cover:

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.

Use System User Access Token

A system user access token is a type of access token that is associated with a system user account, which is an account that is created in the Business Manager for the purpose of managing assets and calling Marketing API. System user access tokens are useful for server-to-server interactions where there is no user present to authenticate. They can be used to perform actions on behalf of the business, such as reading and writing business data, managing ad campaigns, and other ad objects.

One benefit of using a system user access token is that it does not expire, so it can be used in long-running scripts or services that need to access the Graph API. Additionally, because system user accounts are not tied to a specific individual, they can be used to provide a level of separation between personal and business activity on Facebook.

System user tokens are also less likely subject to invalidation for other reasons compared to the long-lived user access tokens.

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 safely stored in your database for subsequent API calls. Moving tokens between your client and server must be done securely over HTTPS to ensure the security of people's accounts. Read more about the implications of moving tokens between your clients and your server.

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 user access tokens can be invalidated or revoked anytime for some reasons, 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.