Authorization and HTTP Headers

  • When calling the Google Ads API, you need both OAuth 2.0 application credentials and a developer token.

  • If making API calls with a Google Ads manager account, you must specify a login-customer-id header.

  • You can use desktop/web app flows or service accounts to obtain OAuth 2.0 credentials.

  • A developer token is required in the developer-token HTTP header for every API call.

  • The request-id response header uniquely identifies an API request and is useful for debugging.

You need both OAuth 2.0 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 OAuth 2.0 for authorizing API requests. Both OAuth 2.0 user authentication flow and service account flow are supported. For more details, see OAuth 2.0 in the Google Ads API.

If you are new to Google APIs, you can use gcloud CLI or the OAuth 2.0 Playground to experiment with OAuth 2.0 credentials and the Google Ads API before writing code for your app.

We recommend that you use one of the OAuth 2.0 libraries available at https://oauth.net/code/ to implement the OAuth 2.0 authorization workflows. However, we have listed the curl instructions in case you need to implement it yourself.

Service accounts

Follow the steps to configure a Google Cloud project for the Google Ads API. Record the service account email and service account key. Next, follow the common instructions in the Service Accounts guide to set up the service account to access your Google Ads account.

User authentication

Follow the steps to configure a Google Cloud Console project for the Google Ads API. Record the client ID and client secret. Next, follow the desktop app flow instructions or the web app flow instructions to generate a refresh token and an access token. The scope to use for Google Ads API access is https://www.googleapis.com/auth/adwords.

Generate new access tokens

Service accounts

When you have the service account email and service account key, follow the Using OAuth 2.0 for Server to Server Applications guide to generate a JWT claim set, which can then be exchanged to obtain an OAuth 2.0 access token. Make sure to select the HTTP/REST tab while following the guide. The OAuth 2.0 scope to use for Google Ads API access is https://www.googleapis.com/auth/adwords. In addition, you can skip the sub parameter when constructing the JWT claim set, because the setup steps grant the service account direct access to the Google Ads account, thus avoiding the need to impersonate a Google Ads user.

You then use the access token in the Authorization HTTP header of every API call to the Google Ads API:

GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

User authentication

Once you have an OAuth 2.0 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 /v22/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 to make calls to the API. If you already have a developer token, you can find it by navigating to https://ads.google.com/aw/apicenter. Sign in to your Google Ads manager account if prompted. If you don't have one, follow the instructions to sign up for a developer token.

You must include your developer token value in the developer-token HTTP header of every API call to the Google Ads API:

GET /v22/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 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. Refer to the Google Ads access model guide to learn more about login customer ID.

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

The Linked customer ID 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
Previous
Overview
Next
REST interface design