Service Accounts

Note: Not all our client libraries currently support service accounts. Service accounts can still be used if you implement the OAuth2 service account flow yourself.

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

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

The Google Ads API allows service account access through G Suite domains.

Service accounts employ an OAuth2 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 OAuth2 flows that require user interactions.
• OAuth2 assertion flow allows your app to impersonate other users if necessary.

Key Point: We strongly recommend using OAuth2 installed app or web flow instead of service accounts unless you need a domain-specific feature (for example, impersonation). OAuth2 installed app and web flows do require an initial user interaction for granting access to the account, but are much simpler to set up.

For the OAuth2 installed app flow, you can persist a refresh token (which never expires) to obtain a new access token whenever necessary. When using one of our client libraries, you can authorize your app by filling out a configuration file.

Prerequisites

• A G Suite 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.

Setting up service account access

First you must generate a service account key in the Google API Console:

1. While logged in to your G Suite account, open the Google API Console.

2. Click Select a project at the top of the screen, then NEW PROJECT. Supply the requested information and click Create. After a moment, the new project becomes the active project.

3. From the menu in the upper left corner, choose IAM & admin, then select Service accounts.

4. Click Create service account at the top.

5. Enter a name for the service account.

6. Check Furnish a new private key, and select JSON as the key type.

7. Check Enable G Suite Domain-wide Delegation, and enter a product name for the consent screen.

8. Click Create. The JSON key file is downloaded to your machine. Store it in a safe place that only you can access.

9. The new service account is shown on the Service Accounts page for the project.

Note: Because user impersonation is controlled only at the domain level, using service accounts and assertion flow with Google OAuth2 requires you to have your own domain registered with G Suite. All users of a domain using a service account with the power to impersonate can impersonate any user in the domain.

Security concerns

Because of G Suite's domain-level control, 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 will have the ability to impersonate any user in the domain.

Another good practice is to allow service accounts to access only one Google API each (using the scope field described in the following section). This is a preemptive measure to limit the amount of data an attacker can access if the service account's key file is compromised.

Granting impersonation abilities

Perform the following steps to grant impersonation abilities to a service account:

1. Add a new authorized API client to your G Suite domain by going to:

   https://admin.google.com/YOUR_DOMAIN/ManageOauthClients
   

   Note: Be sure to replace YOUR_DOMAIN with your actual domain.

2. Add a new authorized API client as the Client Name, using the client ID from the JSON file you generated when you enabled the service account for domain-wide delegation in the steps above.

3. Enter the following for the API scope:

   https://www.googleapis.com/auth/adwords
   

4. Repeat the process for all other service accounts to which you want to grant impersonation power.

You can now use the service account to access your Google Ads account via the OAuth2 assertion flow.

Configuring your client library

Select your language below for instructions to configure your client library.

Java

Not supported.

.NET

OAuth Service Account Flow.

Python

OAuth Service Account Flow.

PHP

Not supported.

Ruby

Not supported.