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 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 lets your app impersonate other users if necessary.

For the OAuth2 desktop 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 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 Cloud 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 does not support using service accounts without impersonation.

Service account access setup

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 Google Workspace. Your app and its users can then impersonate any user in the domain.

  1. Start by creating a service account and creating 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 are the domain administrator, complete the help center instructions.

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

Client library configuration

Select your language for instructions to configure your client library.

Java

OAuth Service Account Flow.

.NET

OAuth Service Account Flow.

Python

OAuth Service Account Flow.

PHP

OAuth Service Account Flow.

Ruby

OAuth Service Account Flow.

Perl

OAuth Service Account Flow.

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.