Service Accounts

This guide discusses how to access the Google Ads API with service accounts.

A service account is an account that belongs to your app instead of to an individual end user. Service accounts enable server-to-server interactions between a web app and a Google service. Your app calls Google APIs on behalf of the service account, so users aren't directly involved.

Service accounts employ an OAuth 2.0 flow that doesn't require human authorization, using instead a key file that only your app can access.

Using service accounts provides two key benefits:

  • Authorization for Google API access is done as a configuration step, thus avoiding the complications associated with other OAuth 2.0 flows that require user interactions.

  • The OAuth 2.0 assertion flow lets your app impersonate other users if necessary.

There are two ways to authorize with service accounts: directly or with impersonation.

Authorization with direct account access

In this option, you give the service account direct access to your Google Ads account.

Account access setup

  1. Start by creating a service account and credentials.

    Download the service account key in JSON format and note the service account ID and email.

  2. Sign in to your Google Ads account as an administrator. Navigate to Admin > Access and security.

  3. Click the + button under the Users tab.

  4. Type the service account email into the Email input box. Select the appropriate level of account access level and click the Add account button. Note that Email and Admin access levels are not supported for service accounts.

  5. The service account is granted access.

Client library configuration

Select the tab corresponding to your programming language for instructions on how to configure your client library.

Java

Set the private key JSON path in your configuration. If you're using an ads.properties file, add the following:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

See the configuration guide for additional details.

.NET

Configure the following keys in your App.config / Web.config. See the configuration guide for additional details.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

Python

Set the private key JSON path in your configuration. If you're using a google-ads.yaml file, YAML string, or dict, add the following:

json_key_file_path: JSON_KEY_FILE_PATH

If you're using environment variables, add the following to your Bash configuration or environment:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

Configure the following keys in your google_ads_php.ini. See the configuration guide for additional details.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Ruby

Configure the following keys in your google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'

Perl

Set the private key JSON path and delegate account ID in your configuration. If you're using a googleads.properties file, add the following:

jsonKeyFilePath=JSON_KEY_FILE_PATH

If you're using environment variables, add the following to your Bash configuration or environment:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

Authorization using impersonation

In this option, you impersonate a user who has access to your Google Ads account using the service account. This approach works only for Google Workspace customers. A service account can only impersonate users (email addresses) in the same Google Workspace.

Prerequisites

  • A Google Workspace domain that you own such as mydomain.com or mybusiness.com

  • A Google Ads API developer token and optionally a test account

  • The client library for the language you're using

  • A Google API Console project that has been configured for the Google Ads API

  • A Google Ads user with permissions on the Google Ads account you want to access. Google Ads doesn't support using service accounts without impersonation.

Service account access setup

Since user impersonation is controlled only at the domain level, using service accounts and assertion flow with Google OAuth 2.0 requires you to have your own domain registered with Google Workspace. Your app and its users can then impersonate any user in the domain.

  1. Start by creating a service account and credentials.

    Download the service account key in JSON format and note the service account ID.

  2. Share the service account ID and the Google Ads API scope (https://www.googleapis.com/auth/adwords) with your domain administrator.

    Request the domain administrator to delegate domain-wide authority to your service account.

  3. If you're the domain administrator, complete the help center instructions.

You can now use the service account to access your Google Ads account with the OAuth 2.0 assertion flow.

Client library configuration

Select the tab corresponding to your programming language for instructions on how to configure your client library.

Java

Set the private key JSON path and delegate account ID in your configuration. If you're using an ads.properties file, add the following:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL

See the configuration guide for additional details.

.NET

Configure the following keys in your App.config / Web.config. See the configuration guide for additional details.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />

Python

Set the private key JSON path and impersonated email in your configuration. If you're using a google-ads.yaml file, YAML string, or dict, add the following:

json_key_file_path: JSON_KEY_FILE_PATH
impersonated_email: IMPERSONATED_EMAIL

If you're using environment variables, add the following to your Bash configuration or environment:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

PHP

Configure the following keys in your google_ads_php.ini. See the configuration guide for additional details.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
impersonatedEmail = "IMPERSONATED_EMAIL"

Ruby

Configure the following keys in your google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'

Perl

Set the private key JSON path and delegate account ID in your configuration. If you're using a googleads.properties file, add the following:

jsonKeyFilePath=JSON_KEY_FILE_PATH
impersonatedEmail=IMPERSONATED_EMAIL

If you're using environment variables, add the following to your Bash configuration or environment:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

Security concerns

Since the service account has domain-level delegation control for your Google Workspace domain, it's important to protect the key file that allows a service account to access the Google services for which it's authorized. This is especially true since that service account has the ability to impersonate any user in the domain.

Another good practice is to allow service accounts to access only the minimum required set of APIs. This is a preemptive measure to limit the amount of data an attacker can access if the service account's key file is compromised.