Service account workflow

  • Service accounts belong to an app and use a key file for authorization without requiring human interaction.

  • Using service accounts simplifies authorization configuration and prevents access issues if the user who authorized access leaves.

  • To set up access, create a service account, download its key, and add the service account email as a user in your Google Ads account with the appropriate access level.

  • Client libraries require configuring the service account key file path for access.

  • Access tokens for the Google Ads API using a service account can be obtained and used in API calls, as demonstrated with a curl example.

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 complications that involve user interaction, storing user credentials, and token management.

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

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 account access level (note that service accounts don't support the Email only access level) and click the Add account button.

  5. The service account is granted access.

  6. Optional: By default, you cannot grant administrator access to a service account. Follow the principle of least privilege and grant administrator access only if your API calls require it. You can upgrade the access as follows:

    • Click the drop-down arrow next to the access level of the service account in the Access level column.
    • Select Admin from the drop-down list.

Client library configuration

Select the tab corresponding to your programming language for instructions on how to configure your client library. If your service account accesses client accounts through a Google Ads manager account (MCC), also set login-customer-id (or loginCustomerId) to the 10-digit customer ID of that manager account without hyphens (see Login customer ID).

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 = "JSON_KEY_FILE_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

See the configuration guide for additional details.

PHP

Configure the following keys in your google_ads_php.ini file.

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

See the configuration guide for additional details.

Ruby

Configure the following keys in your google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'

See the configuration guide for additional details.

Perl

Set the private key JSON path 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

See the configuration guide for additional details.

curl

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

gcloud auth login --cred-file=JSON_KEY_FILE_PATH

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/v25/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_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"
}
Previous
Access model overview
Next
Overview