Service Account Workflow

AI-generated Key Takeaways

• This guide explains how to use service accounts for server-to-server interactions with the Google Ads API, enabling app access without direct user involvement.

• Service accounts offer simplified authorization and the ability to impersonate other users, though impersonation is a legacy approach and discouraged for security reasons.

• Two authorization methods are detailed: direct access, granting the service account permissions to your Google Ads account, and impersonation (for Google Workspace users only), allowing the service account to act on behalf of a specific user.

• Configuration instructions are provided for various client libraries (Java, .NET, Python, PHP, Ruby, Perl) to set up service account authentication.

• Security concerns are highlighted, emphasizing the importance of protecting the service account key file and limiting API access to minimize potential risks.

Note: This guide assumes that you are familiar with the Google Ads access model. If you aren't, we recommend reading the Google Ads access model guide to familiarize yourself with the concepts.

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 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 Ads API access to Google Ads accounts is done as a configuration step, leveraging the authorization and account management features offered by the Google Ads UI. This saves developer effort by not having to build OAuth 2.0 flows and deal with complication that involve user interaction, storing user credentials, etc.

• Authorization for access to Google Ads accounts is not tied to individual user credentials, which may be useful in cases such authorization is expected to continue even if the employee who originally authorized the access leaves the team or the company.

Account access setup

Note: You can associate up to 20 Google Ads accounts (including Google Ads manager accounts) with a single email address. If you need to manage more than 20 accounts using a service account, we recommend adding the service account to a Google Ads manager account instead, and linking all your accounts under this manager account. Refer to the access model guide to learn more.

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

Set the OAuth2Mode and OAuth2SecretsJsonPath on the GoogleAdsConfig instance and use it to initialize the GoogleAdsClient object.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_JSON_SECRETS_PATH",
    ...
};
GoogleAdsClient client = new GoogleAdsClient(config);

See the configuration guide for additional details.

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

curl

Note: This guide shows the instructions of obtaining an access token using gcloud CLI. However, you can use any OAuth 2.0 client library available on the internet. https://oauth.net/code/ lists several language-specific OAuth libraries. You can also refer to Google's OAuth documentation to learn more about the raw HTTP workflow for service accounts.

Start by setting the service account as the active credentials in gcloud CLI.

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

Next, fetch an OAuth 2.0 access token for the Google Ads API.

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

You can now use the access token in your API calls. The following example shows how to run a campaign report using the GoogleAdsService.SearchStream method to retrieve the campaigns in your account. This guide doesn't cover the details of reporting.

curl -i -X POST https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_TOKEN" \
   -H "login-customer-id: LOGIN_CUSTOMER_ID" \
   --data-binary "@query.json"

The contents of query.json are as follows:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}