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 application 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. The Python library is configured as follows:

  • If using a google-ads.yaml file or YAML string, add the following to your configuration to set the path to the private key JSON file in your local environment:

    json_key_file_path: JSON_KEY_FILE_PATH

    Then call the load_from_storage or load_from_string methods:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

  • If you're using a dict to configure the library, include the following key-value pair and call the load_from_dict method, passing in the configuration dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "json_key_file_path": JSON_KEY_FILE_PATH
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

  • 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

    Then call the load_from_env method:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()
  ```

If the json_key_file_path configuration option is present in any of these, configuration methods, and the use_application_default_credentials option is False or unset, the library will automatically authorize using the service account flow.

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 tool such as gcloud CLI or the generate_user_credentials code example to authorize your app to manage all their Google Ads accounts on their behalf.

The library can be initialized using the user's OAuth 2.0 credentials as follows:

If using the gcloud CLI tool (Recommended)

  1. Follow the Generate credentials documentation to set up application default credentials (ADC) in your local environment.

  2. Add the following configuration to your google-ads.yaml or YAML string:

    use_application_default_credentials: true

    Then call either the load_from_storage or load_from_string method:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    If you use a dict to configure the library, include the following key-value pair and call the load_from_dict method:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "use_account_default_credentials": True
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    If you're using environment variables, add the following to your bash configuration or environment:

    export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true

    Then call the load_from_env method:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

If handling OAuth tokens directly

  1. Follow the steps to set up a console project and download the JSON file that includes your project's client ID and client secret.

  2. Clone the Python client library to your machine and change into its directory:

    $ git clone https://github.com/googleads/google-ads-python.git
$ cd google-ads-python

  3. Execute the example, providing an absolute path to the JSON file downloaded in step 1:

    $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON

    Once complete, a refresh token prints to your console. Copy it and save it for the next step.

  4. Configure the library by adding the following settings to your configuration of choice:

    Add the following configuration to your google-ads.yaml or YAML string:

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    Then call either the load_from_storage or load_from_string method:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    If you're using a dict to configure the library, include the following key-value pairs and call the load_from_dict method:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
  "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
  "refresh_token": INSERT_REFRESH_TOKEN_HERE
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    If you're using environment variables, add the following to your bash configuration or environment:

    export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE

    Then call the load_from_env method:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

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. The library can be initialized using the user's credentials as follows, which assumes that your application obtains credentials at runtime, either by executing an authorization flow or by loading them from a datastore:

A dict is the simplest configuration mechanism to use when obtaining credentials at runtime:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

Manual authentication

You can generate auth credentials with any approach and provide them to the GoogleAdsClient manually by instantiating the client class directly. Assuming the credentials object you create is an instance of google.auth.credentials.Credentials, you can pass it in as follows:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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 Python client library provides the following code examples that illustrate how to handle such cases.

  1. The get_account_hierarchy code example shows how to retrieve the list of all accounts under a Google Ads manager account.
  2. The list_accessible_customers 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 login_customer_id setting.