Access and Authentication

There are two access levels for Marketing API. You can upgrade access through App Review and business verification. Note that calls on ANY access level are against production data.

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.

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 your App Dashboard | Settings under Marketing API:

Create a new submission and fill out your information.

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

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

To check for 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.

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_managementpermission.

  • 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.

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.

FAQs

Using Marketing API with business accounts

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.

Use Dev Tier to build an application

Learn how to develop on the API, build and test your application, test it, and add features to expand our ecosystem's capabilities. 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

Creating new applications

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.

Becoming a Facebook Marketing Partner and Badging

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.

Developer Support
Use the bug tool to file issues and the Facebook Marketing Developer community to ask questions. Additional resources here:

Manually Getting Access Tokens

You can get access this way in advanced scenarios. Typically it's easier to get this 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. See:

Ads App Tool

To manually get a token with the API, see Understanding Access Tokens, Video

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

- Business Manager API

- 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/

Via Graph API Explorer

Get a test user access token with Graph API Explorer:

Obtain Short-Lived User Access Token

  • Go to Graph API Explorer
  • In Application, select an app used to obtain the access token
  • Click Get TokenGet User Token
  • Under Events, Groups & Pages, Check manage_pages
  • Click Get Access Token
  • Click i in the access token field
  • Click Open in Access Token Tool to see the token in Access Token Debugger

Check the 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 the followings:
  • 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 that would probably expires in an hour or two
  • Scope: should contain the “manage_page” permission

Exchange for Long-Lived Access Token

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

Get Permanent Page Access Token

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

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

Manually Obtain the Token

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. For additional information, see the authentication guide.

  • If you follow the server-side authentication flow you will be provided with a persistent token.
  • If you follow the client-side authentication flow you will be provided with 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, instead of an individual user, 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 be written to expect that and 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 and send them through the authentication flow to get an updated token if necessary. If this is not possible for your app (e.g., API calls are not directly triggered by a user interface, or are made by periodically run scripts) a different way to prompt the user may be necessary. For example, your app could email instructions to the user.