Google Ads API Authentication: OAuth, Service Accounts & Developer Token (2026)

My Basic Access application for the Google Ads API got reviewed in a few hours instead of the usual days — I wrote about the exact steps in the Basic Access guide. But an approved token doesn't mean anything until you get through the auth handshake, and that's a separate problem entirely — the first time I hit it hard, a Google Merchant Center token died mid-script with no warning at all.

This guide is the part nobody explains cleanly: OAuth2 desktop vs. web flow, the 7-day trap, what a developer token header actually is versus an OAuth token, when a service account is genuinely the right tool (and when it silently isn't), and a two-minute Python test to confirm the whole chain works before you build anything on top of it.

The three (plus one) layers of Google Ads API auth

The single most common beginner mix-up: a developer token is not an OAuth token, and getting one approved doesn't authenticate anything by itself. They're two unrelated credentials that both have to be present on every call, plus a third that only matters once you're working through a manager account.

The developer token itself — how it's generated, and the Test / Explorer / Basic / Standard access levels that gate what it can call — is covered in full in the Basic Access guide. This post assumes you have a token (any level works for testing) and focuses on getting the other layers right.

OAuth2: desktop flow vs. web flow

The Google Ads API supports two OAuth2 flows, and picking the right one saves you a class of bugs later. Per Google's own OAuth internals documentation, the desktop (installed app) flow has offline access — the ability to refresh a token without the user sitting there — turned on by default, so you don't have to explicitly request it. The web application flow doesn't; it needs an explicit access_type=offline parameter on the auth request, or your refresh token never shows up.

For a solo operator or an agency running internal scripts — reporting pulls, budget-pacing checks, bid changes — the desktop flow is the right default. It's what I run for every client account under my own manager account. The web flow is for the other case: an app with a login screen that a third party uses.

If you've already been through the OAuth consent screen for brand verification — Step 4 in the Basic Access guide — you'll recognize this screen. It's the same one; you're just here for a different reason this time.

The trap: Testing mode kills your refresh token in 7 days

This one is documented, but easy to miss. Per Google's own OAuth 2.0 documentation, a Cloud project with an External user type and a Testing publishing status issues refresh tokens that expire after 7 days — no email, no warning banner, nothing. The next call just fails with invalid_grant ("Token has been expired or revoked"), and if the script runs unattended overnight, you find out when the report doesn't show up. I've walked through exactly how this cost me a dead Google Merchant Center token, and the fix, in the Google API access guide for agencies. If your project is the same one you already pushed to In production for brand verification (Step 4 of the Basic Access guide), you've already fixed this — nothing more to do. If not, check now: Cloud Console → APIs and services → OAuth consent screen → Audience tab.

Developer token header + login-customer-id

Two more pieces get confused for each other constantly, and neither is an OAuth concept.

The developer token is not a header you get from an OAuth flow — it's a fixed string from your manager account's API Center (22 characters in my accounts), and it goes on every request as a developer-token HTTP/gRPC header. It identifies the application, not the person calling it, and it's the same value regardless of which Google account authenticated the call.

login-customer-id only matters once your authenticated account has access to a manager (MCC) account. If you're calling the API to act on a client account underneath that MCC, you have to tell Google which account context you're operating in — set the login-customer-id header to the MCC's ID. Skip it and you get USER_PERMISSION_DENIED: "the authorized customer does not have access to the operating customer," even though, from the Google Ads UI, you clearly do.

Service accounts — the catch the quick reference skips

Google's own service account guide makes it look simple: create a service account, download the JSON key, sign into Google Ads as an admin, go to Admin → Access and security, add the service account's email as a user, set json_key_file_path in your config. Four steps, done.

When it's worth it: server-to-server automation with no human in the loop for every token refresh, and — usefully — access that doesn't break the day an employee leaves, since it isn't tied to any one person's Google account. Per Google's guide, one service account email can be added to up to 20 Google Ads accounts; beyond that, Google's guidance is to add it under a manager account instead.

When it isn't: a solo operator or a small team without a Workspace domain. That's my actual setup — every script I run against the Google Ads API uses the desktop OAuth flow above, not a service account, because it's simpler to configure and doesn't require standing up domain-wide delegation for one person's automation.

google-ads.yaml: what the file actually needs

Whichever flow you use, the Python client library reads everything from one YAML file. Here's the shape of it — replace every value, obviously, this isn't a real config:

developer_token: "INSERT_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_REFRESH_TOKEN_HERE"
login_customer_id: "1234567890"   # MCC ID, digits only, no dashes — omit this line entirely for a standalone account
use_proto_plus: True

Two things worth flagging: login_customer_id is the MCC ID without dashes, and it only needs to be set if you're calling through a manager account — leave it out for a standalone account. And use_proto_plus: True isn't optional cosmetics; the client library requires this field in its configuration, and its absence produces confusing type errors that have nothing to do with authentication at all.

Verify it works: a minimal Python test

Before building anything on top of this, confirm the whole chain — OAuth2, developer token, login-customer-id — actually connects. The same principle as testing at Explorer access before applying for Basic: prove the plumbing works on the smallest possible call first.

# 1) One-time: generate a refresh token (desktop OAuth flow)
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ["https://www.googleapis.com/auth/adwords"]
flow = InstalledAppFlow.from_client_secrets_file("client_secret.json", scopes=SCOPES)
credentials = flow.run_local_server(port=8080, prompt="consent")
print(credentials.refresh_token)  # paste this into google-ads.yaml

# 2) First call: does the connection actually work?
from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("google-ads.yaml")
ga_service = client.get_service("GoogleAdsService")

query = "SELECT customer.id, customer.descriptive_name FROM customer LIMIT 1"
response = ga_service.search(customer_id="9876543210", query=query)

for row in response:
    print(row.customer.descriptive_name)

If that returns an account name, every layer — OAuth2, developer token, login-customer-id — is correctly wired. If it fails, the error you get back tells you exactly which layer to fix; see the table below.

Common errors and what actually causes them

All four descriptions above are quoted from Google's official common-errors documentation. The causes and fixes are what I've actually run into wiring this up for client accounts.

Frequently asked questions