Access and Authentication

Access

There are two access levels for Marketing API:

Level Description

Dev Tier

Try and test apps with the API.

Ads Management Standard Access

Get more resources, such as better rate limits, and be nominated to Facebook Partner program.

Each level has restrictions, see Limits. All developers also must follow all Platform Policies. Calls on ANY access level are against production data.

You can upgrade access through App Review and business verification.

Dev Tier

Default for all apps. Use if you are starting to build a tool. Open to all developers, so you can build end-to-end workflows before you get full permissions. Use the API as admin and access unlimited number of ad accounts for people who are admins or advertisers.

Some API calls are not available with Dev Tier because they may belong to multiple accounts, or the affected account can't be identified programmatically.

Ads Management Standard Access

Use this level if you want to get more resources such as a better rate limit. To apply for standard access, go to App Dashboard > App Review > Permissions and Features:

Then, create a new submission and fill out your information:

You need to ask for ads_read permission for Ads Insights, and ads_management permission for Ads Management. Learn more about the permissions.

After you submit your information, Facebook responds with an approval or denial, and information if your app is not qualified for standard access.

To check your current standard access, go to App Dashboard > App Review and you see:

Once your request for Ads Management Standard Access, plus ads_read or ads_management permission is approved, you need to turn your app to Live mode to get standard access.

Permissions

Depending on how you want to access ads, you should get these permissions:

  • Reporting Only - To read ads reports for ad accounts you own or have been granted access to by the ad account owner, request Ads Management Standard Access, along with the ads_read permission.

  • Read and Manage Ads - To both read and manage the ads for ad accounts you own or have been granted access to by the ad account owner, request Ads Management Standard Access, along with the ads_management permission.

  • Reporting Only or Read and Manage - To pull ads reports from a set of clients, and to both read and manage ads from another set of clients, request the Ads Management Standard Access, and both the ads_read and ads_management permissions.

Maintenance

For this level, your app needs to:

  • Be Live.
  • Be approved for the Ads Management Standard Access feature during App Review.
  • Successfully have made at least 1500 Marketing API calls in the last 30 days.
  • Have made Marketing API calls with an error rate of less than 10% in the last 30 days.

Limits

The table below shows the limits on each tier.

Dev Tier Ads Management Standard Access

Account Limits

Manage unlimited number of ad accounts. App admins or developers can make API calls on behalf of ad account admins or advertisers.

Manage unlimited number of ad accounts, assuming you get ads_read or ads_management permission from the ad account.

Rate Limits

Heavily rate-limited per ad account. For development only. Not for production apps running for live advertisers.

Lightly rate limited per ad account.

Business Manager

Limited access to Business Manager and Product Catalog APIs. No Business Manager access to manage ad accounts, user permissions and Pages.

Access to all Business Manager and Product Catalog APIs.

System User

Can create 1 system user and 1 admin system user.

Can create 10 system users and 1 admin system user.

Page Creation

Cannot create pages through the API.

Cannot create pages through the API.

Authentication

Access Tokens

Both Graph API and Marketing API calls require an access token to be passed as a parameter in each API call. Typically, it's easier to get your access token in Ads App Tool when you create a new app. If you are use the Facebook SDKs and want to manually get a token, see Marketing API, SDKs.

To learn more, see Understanding Access Tokens, Video

Get token via Graph API Explorer

Get a test user access token with Graph API Explorer.

Obtain a Short-Lived User Access Token

  1. Go to Graph API Explorer.
  2. In Application, select an app used to obtain the access token.
  3. Click Get Token > Get User Token.
  4. Under Events, Groups & Pages, Check manage_pages.
  5. Click Get Access Token.
  6. Click i in the access token field.
  7. Click Open in Access Token Tool to see the token in Access Token Debugger.

Check Properties in Access Token Debugger

Paste the access token copied in the last step above to the text field and click Debug button. Please check:

  • App ID: The app id mentioned in the prerequisite section.
  • User ID: You, a person who has admin right to the Facebook Page mentioned in the prerequisite section.
  • Expires: A time stamp. A short-lived token expires in an hour or two
  • Scope: Should contain the “manage_page” permission.

Exchange for Long-Lived Access Token

  1. Click Extend Access Token to get a long-lived token.
  2. Copy the long-lived token.
  3. Check the properties of this access token in Access Token Debugger. It should have a longer time, such as 60 days, or Never under Expires. See Long-Lived Access Token.

Get Permanent Page Access Token

  1. Go to Graph API Explorer.
  2. Select your app in Application.
  3. Paste the long-lived access token into Access Token.
  4. Next to Access Token, choose the page you want an access token for. The access token appears as a new string.
  5. Click i to see the properties of this access token.
  6. Click “Open in Access Token Tool” button again to open the “Access Token Debugger” tool to check the properties.

You can check the properties of this page access token in Access Token Debugger:

  • App ID: the app id mentioned in the prerequisite section.
  • Profile ID: the page id mentioned in the prerequisite section.
  • User ID: you, a person who has admin right to the Facebook Page mentioned in the prerequisite section.
  • Expires: Never.

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.

Permissions

For apps to manage ads, someone must grant the app ads_management or ads_read permissions. Use ads_read if you only need Ad Insights API access, to pull reporting information, see Ads Insights API. Use ads_management when you need to read, create and update ads.

Depending on API you use, you need to ask for different permissions:

Product(s) Permission

- Ads Management

- Audience Management

ads_management

- Insights API

ads_read

A Marketing API app is like other Facebook apps and is built on Graph API. See Facebook for websites and Authentication Guide.

Note the following values from your App Summary shown in examples below:

  • App ID: referred to below as <YOUR_APP_ID>
  • App Secret (keep this value secret): referred to below as <YOUR_APP_SECRET>
  • Site URL (a redirect URL): referred to below as <YOUR_URL>

Permissions to Manage Ads

Use the scope parameter to prompt someone for ads_management or ads_read permissions. Your app gets access when someone clicks Allow:

https://www.facebook.com/<API_VERSION>/dialog/oauth?
  client_id=<YOUR_APP_ID>
  &redirect_uri=<YOUR_URL>
  &scope=ads_management

When inputting the YOUR_URL field, put a trailing /. e.g. http://www.facebook.com/

FAQs

There are two access levels for Marketing API. All new App IDs default to Dev Tier and must go through the access tier, regardless of the access level of apps you previously created.

Use Dev Tier to develop on the API, build and test your application. You should use development access to:

  • Test the API and gauge technical complexity
  • Scope resources to build your app
  • Project return on investment
  • Share prototypes with stakeholders to secure resources

Someone grants your app access to manage their ads. If the ad accounts belong to a business in Business Manager, ask the business admins to check that people using your app can access the ad accounts in your app. Sharing Logins is not supported; instead you should use Business Manager.

Developers with Ads Management Standard Access are not automatically included in the Facebook Marketing Program. After you get Ads management Standard Access, you can be nominated to become a Facebook Marketing Partner, and get a badge and speciality designations for your expertise. You can benefit from credibility, marketing support, training and other benefits, see FMD Program.

Use the bug tool to file issues and the Facebook Marketing Developer community to ask questions.

Additional resources are the Bug Tool and the group Facebook Marketing Developers Q/A