Getting Started with Google Ads API: Credentials, Developer Tokens, and Complete Setup Guide

To start using the Google Ads API, you need five credentials—developer token, OAuth 2.0 client ID and secret, refresh token, client customer ID, and optionally a login customer ID—configured in a YAML file or environment variables before making your first API call.

Getting started with the Google Ads API requires careful configuration of authentication credentials and understanding of account hierarchies. According to the google/skills repository, the setup process involves obtaining specific tokens from the Google Ads Manager account and Google Cloud Console, then configuring them properly to avoid common permission errors. This guide walks through the exact steps documented in the official skill files to ensure your first API request succeeds.

Required Google Ads API Credentials

The Google Ads API requires five distinct authentication pieces before any request can be made, as detailed in skills/ads/google-ads-api-quickstart/SKILL.md.

Developer Token

The developer token identifies your application and determines API quota limits. You obtain this by opening the API Center in a Google Ads Manager account and copying the token value. If your token status is Pending (unapproved), you must restrict all API calls to Google Ads Test Accounts only—attempting to query production accounts will trigger the DEVELOPER_TOKEN_NOT_APPROVED error.

OAuth 2.0 Client ID and Secret

These credentials authenticate your application with Google's OAuth server. Create them in the Google Cloud Console by creating a new project, enabling the Google Ads API, configuring an External OAuth consent screen (adding your Google Ads test user), and creating a Desktop App client. Download the resulting client_secrets.json file, which contains your client_id and client_secret.

OAuth 2.0 Refresh Token

The refresh token allows your application to obtain new access tokens without user interaction. Generate this by running gcloud auth application-default login with your downloaded client_secrets.json. The CLI writes the refresh token to ~/.config/gcloud/application_default_credentials.json, which you will extract for your configuration.

Client Customer ID

This is the 10-digit Google Ads account you want to query. Find it in the top-right corner of the Google Ads UI, ensuring you remove any hyphens before using it in API calls. The Python quick-start script in references/python.md automatically normalizes this by calling replace("-", "") on the input string.

Login Customer ID (Optional)

Required when using a manager-client hierarchy, the login customer ID specifies the Manager account that owns the client account. Use the same 10-digit format as the client customer ID, but sourced from your manager account dashboard. Omitting this when required produces the USER_PERMISSION_DENIED error.

Configuration and Setup

Creating the google-ads.yaml File

The simplest configuration method uses a YAML file with your credentials. Create a google-ads.yaml file in your working directory:

developer_token: INSERT_DEVELOPER_TOKEN_HERE
client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_OAUTH2_REFRESH_TOKEN_HERE

# Uncomment if using a manager-client hierarchy

# login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

use_proto_plus: true

As implemented in google/skills, the GoogleAdsClient.load_from_storage() method automatically searches for this file in the current working directory before falling back to default paths.

Environment Variable Alternative

You can also configure credentials via environment variables. Set GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, and GOOGLE_ADS_REFRESH_TOKEN, then instantiate the client using GoogleAdsClient.load_from_env().

Running Your First Query

The following Python script from skills/ads/google-ads-api-quickstart/references/python.md demonstrates loading credentials, normalizing the customer ID, and streaming campaign data:

import argparse, os, sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    service = client.get_service("GoogleAdsService")
    query = "SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id"
    print("Querying Google Ads API...")
    try:
        stream = service.search_stream(customer_id=customer_id, query=query)
        for resp in stream:
            for row in resp.results:
                print(f"Campaign found: ID = {row.campaign.id}, Name = '{row.campaign.name}', Status = {row.campaign.status.name}")
    except GoogleAdsException as ex:
        print(f"Request ID '{ex.request_id}' failed with status '{ex.error.code().name}':")
        for err in ex.failure.errors:
            print(f"\tError: {err.message}")
        sys.exit(1)

if __name__ == "__main__":
    # Prefer a local yaml config, then env vars, then default paths

    local_cfg = os.path.join(os.getcwd(), "google-ads.yaml")
    if os.path.exists(local_cfg):
        googleads_client = GoogleAdsClient.load_from_storage(local_cfg)
    elif "GOOGLE_ADS_DEVELOPER_TOKEN" in os.environ:
        googleads_client = GoogleAdsClient.load_from_env()
    else:
        googleads_client = GoogleAdsClient.load_from_storage()  # default search

    parser = argparse.ArgumentParser(description="Lists campaigns for a specified customer ID.")
    parser.add_argument("-c", "--customer_id", required=True, help="10-digit customer ID.")
    args = parser.parse_args()
    normalized_id = args.customer_id.replace("-", "")
    main(googleads_client, normalized_id)

Run this script with: python script.py -c 1234567890

Dynamic Version Resolution

The skill enforces dynamic resolution of both the Google Ads API version (e.g., v24) and language runtime versions. At runtime, you should scrape the latest version from the Google Ads API Release Notes or the googleapis GitHub repository.

Supported runtime minimums include Python 3.9+, Java 11+, .NET 6.0+, PHP 8.1+, Ruby 3.0+, and Perl 5.28.1+. If scraping fails, fall back to safe defaults (API v24, Python 3.9+) as documented in SKILL.md.

Common Pitfalls and Troubleshooting

Pending Developer Token Restrictions

Using a Pending developer token against a production account triggers the DEVELOPER_TOKEN_NOT_APPROVED error. Solution: Work exclusively with test accounts until your token receives Explorer, Basic, or Standard access approval.

Manager-Client Hierarchy Errors

Missing the login_customer_id parameter when querying client accounts under a manager account produces USER_PERMISSION_DENIED. Solution: Add the manager's 10-digit ID to your google-ads.yaml configuration file or environment variables.

Customer ID Formatting Issues

Including hyphens in customer IDs causes API failures. Solution: Strip hyphens before passing the ID to the API. The Python quick-start script handles this automatically via args.customer_id.replace("-", "").

Summary

• Five credentials required: developer token, OAuth 2.0 client ID/secret, refresh token, client customer ID, and optional login customer ID
• Pending tokens restricted: Unapproved developer tokens only work with test accounts, not production data
• Configuration methods: Use google-ads.yaml file or environment variables loaded via GoogleAdsClient.load_from_storage() or GoogleAdsClient.load_from_env()
• Manager hierarchies: Always include login_customer_id when accessing client accounts through a manager account to avoid permission errors
• Dynamic versioning: Automatically resolve the latest API version and runtime requirements, falling back to v24 and Python 3.9+ if needed

Frequently Asked Questions

How do I get a Google Ads API developer token?

Navigate to the API Center in your Google Ads Manager account (not a standard account) and copy the token string. New tokens begin with a Pending status, which restricts you to test accounts only until Google approves your application for Basic or Standard access.

Why am I getting DEVELOPER_TOKEN_NOT_APPROVED error?

This error occurs when you attempt to query a production Google Ads account using a developer token that has not yet been approved. While pending, tokens only work with Google Ads Test Accounts. Create a test account from the API Center and use that account's customer ID until your token status changes.

What is the difference between client_customer_id and login_customer_id?

The client_customer_id is the 10-digit account you want to query data from, while the login_customer_id is the manager account used to access that client. You only need the login customer ID when using manager account credentials to access client accounts. Both IDs must be provided without hyphens.

How do I handle API version updates automatically?

Implement dynamic version resolution by scraping the latest version number from the Google Ads API Release Notes or the googleapis GitHub repository. If scraping fails, default to a known stable version like v24. The google/skills repository recommends checking minimum runtime versions (Python 3.9+, Java 11+, etc.) against the Client Libraries documentation before upgrading.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}