Access and Authentication

There are three access levels to the Marketing APIs.

You can upgrade access after you meet criteria described later.

Note that calls on ANY access level are against production data.

Each level has restrictions, see Limits. All developers also must follow all Platform Policies.

Development

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 up to 5 ad accounts for people who are admins or advertisers. To set up the ad account list, see Standard Accounts.

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

Basic

To scale out to a limited set of initial customers.

Criteria:

1. App successfully makes at least 1000 API calls with an error rate of less than 10% in the last 30 days
2. Apps creates sufficient ads that pass ad review and do not contain bad creatives
3. Login flow is clear; user knows what permissions are requested

Once you have an app, apply for basic access through your app's 'Status and Review' panel.

Submit an application for the 'Ads Management Basic Access' Feature.

See Basic Application. To check if you have basic access, see app dashboard, 'Status and Review' with 'Ads Management Basic Access':

Standard

For heavy ad demands; no limit on number of customer accounts.

You get this level only after acceptance to the basic level, you cannot skip levels. Submit your app to Standard Access.

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

To check for standard access, go to app dashboard, 'Status and Review' and you see:

Limits

Apply for Basic

To apply for basic access, go to app, 'Status and Review' and create a new submission:

Submit apps for 'Ads Management Basic Access':

After your app is accepted, make API calls for up to 25 ad accounts.

To define these accounts, set up an account list.

You still need to ask for ads_management permission for Ads Management) or ads_read permission for Ads Insights.

If you use the Pages API, request manage_pages permissions to manage page posts for each page.

If your app uses the manage_pages permission, you need a separate app review from Marketing API access.

Managing Account Lists

We automatically add accounts that you make API calls against to your account lists, up to the maximum number for your access level.

If you exceed this limit, API calls return an error.

1.Use the Ads API account configuration tool to add or remove accounts from this list.

2.In your app dashboard, go to Apps > Settings > Advanced. Under Advertising Accounts click Marketing API. The account configuration tool opens.

Enter in an account ID.

You should enter a numeric value; do not include act_ from the account ID.

Check the account IDs match exactly.

When you reach your maximum, Add is disabled.

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 development access 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

Evaluating acceptance for access
There are several factors we evaluate and the specific details for each level are above.

Time to review apps for basic and standard access?
Going from development to basic access requires review in about 3 business days.

Review times depend on the load of apps being reviewed.

Basic to standard access requires more in-depth business review, averaging two weeks but depends on the complexity of the app and its business case.

Existing standard access and creating new applications
All new App ID default to development access and must go through the access levels, regardless of access of previous apps.

Becoming a Facebook Marketing Partner and Badging
Developers with Standard access are not automatically included in the Facebook Marketing Program.

After you get 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:

• Bug Tool
• Facebook Marketing Developers Q/A

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

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

For development and basic access apps, configure a list of ad accounts your app is able to make API calls for in an Account List.

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

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 Token → Get 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 as 60 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.