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 required credentials. For a deeper dive into the Google Ads API access model, read the [Google Ads access model guide](https://developers.google.com/google-ads/api/docs/oauth/access-model). ## Credentials Access to the Google Ads API requires OAuth 2.0 credentials and, in some cases, a login customer ID. ### 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](https://developers.google.com/google-ads/api/docs/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 that 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 that you are using for access permissions. For more details, see the [related documentation](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid). 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](https://developers.google.com/google-ads/api/docs/client-libs/java/config-file) 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](https://developers.google.com/identity/protocols/oauth2#serviceaccount) 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=INSERT_PATH_TO_JSON_HERE # Only add this key if you are using Google Workspace domain-wide delegation # to impersonate a user who has access to the Google Ads account. # api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE Refer to the [service account workflow guide](https://developers.google.com/google-ads/api/docs/oauth/service-accounts) 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 grant the user access to a Google Ads API manager account and link all target Google Ads accounts under that manager account. 2. The user runs a command-line tool such as [`gcloud` CLI](https://cloud.google.com/sdk/gcloud) or the [`GenerateUserCredentials` code example](https://github.com/googleads/google-ads-java/blob/HEAD/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/GenerateUserCredentials.java) 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 Refer to the [single-user authentication workflow guide](https://developers.google.com/google-ads/api/docs/oauth/single-user-authentication) 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`](https://github.com/googleads/google-ads-java/blob/HEAD/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/GenerateUserCredentials.java) code example is a command-line tool 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 or web apps that require user authentication. For multi-user applications, store your application's OAuth 2.0 client ID and client secret in `ads.properties` (or another configuration store), while storing each end user's refresh token securely in your application database and passing it programmatically at runtime when building `UserCredentials` and `GoogleAdsClient`: api.googleads.clientId=INSERT_CLIENT_ID_HERE api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE Refer to the [multi-user authentication workflow guide](https://developers.google.com/google-ads/api/docs/oauth/multi-user-authentication) to learn more. ## Manage 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 illustrate how to handle such cases: 1. The [`GetAccountHierarchy`](https://github.com/googleads/google-ads-java/blob/HEAD/google-ads-examples/src/main/java/com/google/ads/googleads/examples/accountmanagement/GetAccountHierarchy.java) code example shows how to retrieve the list of all accounts under a Google Ads manager account. 2. The [`ListAccessibleCustomers`](https://github.com/googleads/google-ads-java/blob/HEAD/google-ads-examples/src/main/java/com/google/ads/googleads/examples/accountmanagement/ListAccessibleCustomers.java) 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](https://cloud.google.com/docs/authentication/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 required 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 (or call `.enableApplicationDefaultCredentials()` on `GoogleAdsClient.newBuilder()`). When using Application Default Credentials, the client ID, client secret, and refresh token shouldn't be set.