Configuration

Page Summary

outlined_flag

• The library defaults to a configuration file at System.getProperty("user.home") + "/ads.properties" but this can be overridden at runtime.

• Configuration can be done through a Java Properties file with specific key-value pairs depending on the authentication flow.

• Different sets of supported keys exist for desktop/web application flows and service account flows.

• Environment variables corresponding to configuration file properties can also be used for configuration.

• Various configuration approaches, including environment variables and properties files, can be combined when building the GoogleAdsClient.

The Java client library looks for a configuration file named ads.properties in your home directory (System.getProperty("user.home") + "/ads.properties", or ~/ads.properties). You can override this path and filename at runtime when constructing the GoogleAdsClient using either of the following mechanisms:

• Call fromPropertiesFile(PATH_TO_CONFIG_FILE), where PATH_TO_CONFIG_FILE is the File path and filename of your configuration file.
• Set the environment variable GOOGLE_ADS_CONFIGURATION_FILE_PATH to the path and filename of your configuration file, and then call fromPropertiesFile().

The format of the configuration file is a standard Java Properties file of key-value pairs. The supported keys vary depending on the chosen authentication flow.

Supported keys for desktop and web application flows

If you are using the single-user or multi-user application flow, the supported keys are as follows:

# Credential for accessing Google's OAuth servers.
# Provided by console.cloud.google.com.
api.googleads.clientId=INSERT_CLIENT_ID_HERE

# Credential for accessing Google's OAuth servers.
# Provided by console.cloud.google.com.
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

# Renewable OAuth credential associated with 1 or more Google Ads accounts.
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. You can also specify this later in code if your application
# uses multiple manager account + OAuth pairs.
#
# api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

# Only required if explicitly instructed by the service documentation.
# api.googleads.linkedCustomerId=INSERT_LINKED_CUSTOMER_ID_HERE

# Maximum allowed response payload size, in bytes.
# Customize this to allow response sizes for GoogleAdsService.search and
# GoogleAdsService.searchStream API calls to exceed the default limit of 64MB.
# api.googleads.maxInboundMessageBytes=INSERT_MAX_INBOUND_MESSAGE_BYTES_HERE

# Specifies whether to use Application Default Credentials.
api.googleads.useApplicationDefaultCredentials=false

Supported keys for service accounts

If you are using the service account flow, the supported keys are as follows:

# Path to the service account secrets file in JSON format.
# Provided by console.cloud.google.com.
api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE

# Optional: Email address of the user to impersonate when using Google Workspace
# domain-wide delegation. This should be a user who has access to your Google Ads
# account and is in the same Google Workspace domain as the service account.
# api.googleads.serviceAccountUser=INSERT_USER_EMAIL_ADDRESS_HERE

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. You can also specify this later in code if your application
# uses multiple manager account + OAuth pairs.
#
# api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Use environment variables

The library supports all of the standard Google Ads API client library environment variables. The following table shows the environment variable that corresponds to each configuration file property:

Once you have set the appropriate environment variables, configure your GoogleAdsClient by calling fromEnvironment() on the builder:

GoogleAdsClient googleAdsClient =
    GoogleAdsClient.newBuilder()
        .fromEnvironment()
        .build();

Combine configuration approaches

The GoogleAdsClient and its builder support combining different configuration strategies. For example, you can use environment variables to configure the credentials of the instance and a properties file for other attributes using the following snippet:

GoogleAdsClient googleAdsClient =
    GoogleAdsClient.newBuilder()
        .fromEnvironment()
        .fromPropertiesFile()
        .build();

You can make further changes at runtime using the builder's other configuration methods before calling build().

Developer token sunset

Following the developer token sunset on September 9, 2026, API access levels are determined by your Google Cloud project on the API server rather than a developer token:

• Configuration changes: You no longer need to specify api.googleads.developerToken in ads.properties or GOOGLE_ADS_DEVELOPER_TOKEN in your environment variables. Existing applications that still specify api.googleads.developerToken continue to work because API servers ignore the developer-token header (though a future major version of the Google Ads API will reject it).
• Client library version requirements: To omit the developer token from your configuration, use google-ads-java v46.0.0 or later, which removed client-side validation requiring a developer token.
• Authorization error changes: If a Google Cloud project with only Test access calls a production Google Ads account, v25 and later of the Google Ads API return AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION, whereas v24 and earlier return AuthorizationError.ACTION_NOT_PERMITTED.