Authentication and Authorization

Like other Google APIs, the Google Ads API uses the OAuth 2.0 protocol for authentication and authorization. OAuth 2.0 enables your Google Ads API client app to access a user's Google Ads account without having to handle or store the user's login info.

Understand the Google Ads Access Model

To work effectively with the Google Ads API, you should understand how the Google Ads access model works. We recommend reading the Google Ads access model guide.

OAuth workflows

There are three common workflows used when working with the Google Ads API.

Service account flow

This is the recommended workflow if your workflow doesn't require any human interaction. This workflow requires a configuration step, where the user adds a service account to their Google Ads account. The app can then use the service account's credentials to manage the user's Google Ads account. To configure this, create and download the JSON key file in the Google Cloud Console, then copy google_ads_config.rb to your home directory and modify it to specify your service account keyfile location and the email address of the user to impersonate:

  # You can also authenticate using a service account. If "keyfile" is
  # specified below, then service account authentication will be assumed and
  # the above authentication fields ignored. Read more about service account
  # authentication here:
  # https://developers.google.com/google-ads/api/docs/oauth/service-accounts
  # c.keyfile = 'path/to/keyfile.json'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

If you prefer not to store this information in a file and would rather use environment variables, you can set GOOGLE_ADS_JSON_KEY_FILE_PATH and GOOGLE_ADS_IMPERSONATED_EMAIL respectively.

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

You can also pass the information programmatically at runtime, by using the googleauth gem to create credentials from a service account JSON file:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file
key_file = "/path/to/your/service-account-key.json"

# Define the scopes needed for the Google Ads API
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials
credentials = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
end

Refer to the service account workflow guide to learn more.

Single-user authentication flow

This workflow may be used if you cannot use service accounts. This workflow requires two configuration steps:

  1. Give a single user access to all the accounts to be managed using the Google Ads API. A common approach is to give the user to a Google Ads API manager account, and link all the Google Ads accounts under that manager account.
  2. The user runs a command-line tool such as gcloud or the GenerateUserCredentials code example to authorize your app to manage all their Google Ads accounts on their behalf.

The OAuth 2.0 credentials can be configured for Ruby by copying the google_ads_config.rb file to your home directory and modifying it to include your developer token, client ID, client secret, and refresh token:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

The client will automatically read the configuration file from the home directory if instantiated with no arguments:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Alternatively, if you prefer to store the file elsewhere, you can instantiate the client by passing the path to where you keep this file:

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

If you prefer not to store this information in a file and would rather use environment variables, you can set each of them:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

You can also pass the information programmatically at runtime:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

Refer to the single-user authentication workflow guide to learn more.

Multi-user authentication flow

This is the recommended workflow if your app allows users to sign in and authorize your app to manage their Google Ads accounts on their behalf. Your app builds and manages the OAuth 2.0 user credentials. This workflow can be configured similarly to the single-user flow, but with the login_customer_id specified as well.

We recommend you use a configuration file. Copy the google_ads_config.rb file to your home directory and modify it to include your developer token, client ID, client secret, refresh token, and customer ID:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

  # Required for manager accounts only: Specify the login customer ID used to
  # authenticate API calls. This will be the customer ID of the authenticated
  # manager account. If you need to use different values for this field, then
  # make sure fetch a new copy of the service after each time you change the
  # value.
  # c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

The client will automatically read the configuration file from the home directory if instantiated with no arguments:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Alternatively, if you prefer to store the file elsewhere, you can instantiate the client by passing the path to where you keep this file:

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

If you prefer not to store this information in a file and would rather use environment variables, you can set each of them:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

You can also pass the information programmatically at runtime:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Refer to the multi-user authentication workflow guide to learn more. The Ruby client library includes a code example for reference. The GenerateUserCredentials is a command line code example that illustrates how to obtain user authentication at runtime to manage their Google Ads accounts on their behalf. You can use this code example as a reference to build desktop apps that require user authentication.

What if my user manages multiple accounts?

It is common for a user to manage more than one Google Ads account, either through direct access to accounts, or through a Google Ads manager account. The Ruby client library provides the following code examples that illustrates how to handle such cases.

  1. The GetAccountHierarchy code example shows how to retrieve the list of all accounts under a Google Ads manager account.
  2. The ListAccessibleCustomers code example shows how to retrieve the list of all accounts that a user has direct access to. These accounts can then be used as valid values for the LoginCustomerId setting.

Application default credentials

The Ruby client library also supports authenticating with application default credentials (ADC). It lets you set the default credentials for your application, without needing to configure the OAuth 2.0 information within your application configuration.

This is particularly useful for local development or for development against different Google APIs, as you can reuse the same credentials, provided that they can access the correct OAuth 2.0 scopes.

For the Google Ads API, make sure your application default credentials can access the https://www.googleapis.com/auth/adwords OAuth 2.0 scope.

To use application default credentials, we recommend using the Google Cloud command line tool and authenticating for ADC:

gcloud auth application-default login

This command will open a web browser to complete the authentication flow for your Google Account. Once authorized, it stores credentials in a standard location. You then need to update your application to use ADC.

We recommend you use a configuration file. Copy the google_ads_config.rb file to your home directory, then add your developer token and set use_application_default_credentials to true:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # You can also authenticate using Application Default Credentials (ADC)
  # To understand how ADC discovers credentials in a given environment,
  # see: https://developers.google.com/identity/protocols/application-default-credentials.
  c.use_application_default_credentials = true

If you prefer not to store this information in a file and would rather use environment variables, you can set GOOGLE_ADS_DEVELOPER_TOKEN and GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

You can also pass the information programmatically at runtime. When you initialize the client in your Ruby code, do not provide explicit OAuth2 credentials. The library will automatically detect and use the credentials set up by the Google Cloud command line tool. You will still need to specify your developer token.

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = "YOUR_LOGIN_CUSTOMER_ID"

  # Do NOT include oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

Refer to the configuration page for further details about the available options to configure the Ruby client library.