You need both OAuth 2.0 application credentials and a developer
token when calling the Google Ads API. If you're making API calls
with a Google Ads manager account, you also need to specify a login-customer-id
header with each request. This page describes how to set these values and
documents several additional API-specific HTTP headers that are sent and
received when using the REST interface.
OAuth 2.0 credentials
The Google Ads API uses application credentials for identifying and authorizing API requests. Both OAuth 2.0 clients and service accounts can be configured. For more details about configuring client-side authorization, see OAuth2 in the Google Ads API.
If you are new to Google APIs, you can use oauth2l or the OAuth 2.0 Playground to experiment with application credentials and the Google Ads API before writing the code for your app.
Using desktop or web app flows
Follow the steps to configure a Google API Console project for the Google Ads API. Record the client ID and client secret, then come back to this page.
Once you've created an OAuth client, follow the desktop app flow instructions or the web app flow instructions to generate a refresh token and an access token.
Using service accounts
Follow the common instructions in the Service Accounts guide to set up service account access for the Google Ads API.
Once you've set up a service account to access your Google Ads account, follow the
Using OAuth 2.0 for Server to Server
Applications
guide, making sure to select the HTTP/REST
tab. The scope
to use for Google Ads API
access is https://www.googleapis.com/auth/adwords
.
Generating new access tokens
Once you have a client ID, client secret, and refresh token, you can
generate a new access token for use in API calls with the
curl
command line tool:
curl \
--data "grant_type=refresh_token" \
--data "client_id=CLIENT_ID" \
--data "client_secret=CLIENT_SECRET" \
--data "refresh_token=REFRESH_TOKEN" \
https://www.googleapis.com/oauth2/v3/token
You then use the access token returned by the curl request in the
Authorization
HTTP header of every API call to the Google Ads API:
GET /v18/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
Request headers
Developer token
The Google Ads API also requires a developer token in order to make calls to the API. You can apply for a token for your manager account directly from the Google Ads UI. For more details about getting set up with a developer token, see Obtain Your Developer Token.
You need to include your developer token value in the developer-token
HTTP
header of every API call to the Google Ads API:
GET /v18/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
Login customer ID
For Google Ads API calls made by a manager to a client account (that is, when
logging in as a manager to make API calls to one of its client accounts), you
also need to supply the login-customer-id
HTTP header. This value represents
the Google Ads customer ID of the manager making the API call.
Including this header is equivalent to choosing an account in the Google Ads UI
after signing in or clicking on your profile image at the top-right corner of
the page. When specifying the customer ID, be sure to remove any hyphens (—),
for example: 1234567890
, not 123-456-7890
.
GET /v18/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
Linked customer ID
This header is only used by third-party app analytics providers when uploading conversions to a linked Google Ads account. See the API Call Structure guide for more details.
...
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
linked-customer-id: LINKED_CUSTOMER_ID
Response headers
The following headers are returned in HTTP responses from the API.
Request ID
The request-id
is a string that uniquely identifies the API request. When
debugging or troubleshooting problems with specific API calls, the request-id
is an important identifier to have handy when contacting Google developer
support.
request-id: 2a5Cj89VV7CNhya1DZjjrC