Authentication and Authorization

Like other Google APIs, the Google Ads API uses the OAuth 2.0 protocol for authentication and authorization. OAuth 2.0 enables your Google Ads API client app to access a user's Google Ads account without having to handle or store the user's login info.

This guide covers how to configure the Java client library for Google Ads API authentication using the three most common OAuth 2.0 flows, along with explaining the necessary credentials.

For a deeper dive into the Google Ads API access model, read the Google Ads access model guide.

Credentials

Access to the Google Ads API requires a developer token, OAuth 2.0 credentials and, in some cases, a login customer ID.

Developer token

The developer token is linked to a manager account and can be found in the Google Ads web interface.

Although the developer token is linked to a manager account, it doesn't provide access to that account. Instead, the developer token grants access to the API in general, and account-level access is configured through OAuth 2.0.

In the client library, the developer token is specified by the api.googleads.developerToken key in your ads.properties file.

OAuth 2.0 credentials

To authorize as Google Account users with access to Google Ads accounts, you must provide a set of OAuth 2.0 credentials. The type of credentials required varies depending on the OAuth 2.0 flow being used.

The library supports three flows:

  • Service account flow
  • Single-user authentication flow
  • Multi-user authentication flow

Refer to the OAuth Overview for details on Google Ads API OAuth flows, and follow the instructions for the flow that best meets your needs to obtain the required credentials.

Login customer ID

Optionally, specify the customer ID of a manager account which provides access to the serving account. This must be specified if your access to the customer account is through a manager account. There is no need to specify all manager accounts on the path to the customer ID, only the topmost manager ID which you are using for access permissions. For more details, see the related documentation.

In the client library, the login customer ID is specified by the api.googleads.loginCustomerId key in your ads.properties file.

Configuration

You can configure the client library with an ads.properties file, environment variables, or programmatically. This guide focuses on using an ads.properties file. See the Configuration guide for details on all options.

If using an ads.properties file, place it in your home directory: ~/ads.properties.

OAuth workflows

There are three common workflows used when working with the Google Ads API.

Service account flow

This is the recommended workflow if your workflow doesn't require any human interaction. This workflow requires a configuration step, where the user adds a service account to their Google Ads account. The app can then use the service account's credentials to manage the user's Google Ads account.

Once you have the private key JSON file, add the following to your ads.properties file:

api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

Refer to the service account workflow guide to learn more.

Single-user authentication flow

This workflow may be used if you cannot use service accounts. This workflow requires two configuration steps:

  1. Give a single user access to all the accounts to be managed using the Google Ads API. A common approach is to give the user to a Google Ads API manager account, and link all the Google Ads accounts under that manager account.
  2. The user runs a command-line tool such as gcloud or the GenerateUserCredentials code example to authorize your app to manage all their Google Ads accounts on their behalf.

Once you have these credentials, add the following to your ads.properties file:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

Refer to the single-user authentication workflow guide to learn more.

Multi-user authentication flow

This is the recommended workflow if your app allows users to sign in and authorize your app to manage their Google Ads accounts on their behalf. The GenerateUserCredentials is a command line code example that illustrates how to obtain user authentication at runtime to manage their Google Ads accounts on their behalf. You can use this code example as a reference to build desktop apps that require user authentication.

Add the following to your ads.properties file:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

Refer to the multi-user authentication workflow guide to learn more.

What if my user manages multiple accounts?

It is common for a user to manage more than one Google Ads account, either through direct access to accounts, or through a Google Ads manager account. The Java client library provides the following code examples that illustrates how to handle such cases.

  1. The GetAccountHierarchy code example shows how to retrieve the list of all accounts under a Google Ads manager account.
  2. The ListAccessibleCustomers code example shows how to retrieve the list of all accounts that a user has direct access to. These accounts can then be used as valid values for the LoginCustomerId setting.

Application default credentials

The Java client library also supports authenticating with application default credentials.

This is particularly useful for local development or for development against different Google APIs, as you can reuse the same credentials, provided that they can access the correct OAuth 2.0 scopes.

For the Google Ads API, make sure your application default credentials can access the https://www.googleapis.com/auth/adwords OAuth 2.0 scope.

To use application default credentials, set the api.googleads.useApplicationDefaultCredentials option to true in your ads.properties file. When using application default credentials, the client ID, client secret, and refresh token shouldn't be set.