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

> Learn to set up Google Ads API credentials, developer tokens, and more. Follow our complete guide to get started with the Google Ads API for your advertising needs.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: getting-started
- Published: 2026-08-09

---

**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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/google-ads.yaml) file in your working directory:

```yaml
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`](https://github.com/google/skills/blob/main/skills/ads/google-ads-api-quickstart/references/python.md) demonstrates loading credentials, normalizing the customer ID, and streaming campaign data:

```python
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](https://developers.google.com/google-ads/api/docs/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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.