Google Ads Setup

Step-by-step guide to getting a developer token, OAuth credentials, and refresh token for the Google Ads API.

The Google Ads API requires four separate credentials. This guide walks through getting each one.

Overview

You need:

Developer token — issued by Google Ads, tied to your manager account
OAuth client ID + secret — created in Google Cloud Console
Refresh token — generated by running an OAuth flow
Customer ID — the ad account you want to manage
Manager ID — your MCC (manager) account ID (if applicable)

Step 1: Get a developer token

The developer token authorizes API access at the account level. It's tied to your manager (MCC) account.

Go to Google Ads and sign in to your manager account (not a child account)
Click the wrench icon (Tools & Settings) → Setup → API Center
If you don't see API Center, your account may not be an MCC. You need a manager account to get a developer token
Click Apply for basic access if you haven't already
Copy the Developer token shown on the page

Test vs. production token: New tokens start in test mode, which only allows access to test accounts. For production use, you'll need to apply for basic access approval. This typically takes 1-3 business days.

Step 2: Create OAuth 2.0 credentials

Go to Google Cloud Console
Create a new project (or select an existing one)
Enable the Google Ads API:
- Navigate to APIs & Services → Library
- Search for "Google Ads API" and click Enable
Create OAuth credentials:
- Go to APIs & Services → Credentials
- Click Create Credentials → OAuth client ID
- Application type: Desktop app
- Name it anything (e.g. "ads-as-code")
- Click Create
Copy the Client ID and Client Secret

OAuth consent screen: If prompted to configure the consent screen, set it to External and add your email as a test user. You don't need to publish it for personal use.

Step 3: Generate a refresh token

The refresh token lets the SDK authenticate without requiring an interactive login each time.

Use the Google Ads OAuth Playground or run the built-in auth command:

ads auth google

The CLI will open a browser, ask you to sign in with the Google account that has access to your ad accounts, and save the refresh token automatically.

Manual method (if the CLI auth flow fails):

Go to OAuth 2.0 Playground
Click the gear icon → check Use your own OAuth credentials
Enter your Client ID and Client Secret
In the scope box, add: https://www.googleapis.com/auth/adwords
Click Authorize APIs and sign in
Click Exchange authorization code for tokens
Copy the Refresh token

Step 4: Find your customer ID and manager ID

Customer ID — the ad account you want to manage:

Sign in to Google Ads
The customer ID appears at the top right as XXX-XXX-XXXX
Strip the dashes: 1112223333

Manager ID — your MCC account:

Sign in to your manager account
The manager account ID appears at the top right
Strip the dashes

If you manage the ad account directly (no MCC), you can omit managerId from the config.

Step 5: Set up credentials

Create ~/.ads/credentials.json:

~/.ads/credentials.json

{
  "google_client_id": "123456789-abcdefg.apps.googleusercontent.com",
  "google_client_secret": "GOCSPX-your-secret",
  "google_refresh_token": "1//your-refresh-token",
  "google_developer_token": "your-developer-token",
  "google_customer_id": "1112223333",
  "google_manager_id": "4445556666"
}

Then reference the customer ID in your project config:

ads.config.ts

import { defineConfig } from '@upspawn/ads'

export default defineConfig({
  google: {
    customerId: '1112223333',
    managerId: '4445556666',
  },
})

Step 6: Verify

ads auth google

Expected output: Connected to Google Ads account: [Account Name] (1112223333)

If the command succeeds, you're ready to run ads plan and ads apply.

Environment variable alternative

Instead of ~/.ads/credentials.json, you can set environment variables:

export GOOGLE_ADS_CLIENT_ID="..."
export GOOGLE_ADS_CLIENT_SECRET="..."
export GOOGLE_ADS_REFRESH_TOKEN="..."
export GOOGLE_ADS_DEVELOPER_TOKEN="..."
export GOOGLE_ADS_CUSTOMER_ID="1112223333"
export GOOGLE_ADS_MANAGER_ID="4445556666"

Credentials are resolved in this order: explicit config in ads.config.ts → ~/.ads/credentials.json → environment variables.

Troubleshooting

DEVELOPER_TOKEN_NOT_APPROVED Your developer token is in test mode. It can only access test accounts. Apply for basic access in API Center or use a test account for development.

CUSTOMER_NOT_FOUND The customer ID doesn't match the authenticated account. Double-check the ID (no dashes) and that the authenticated user has access to that account.

USER_PERMISSION_DENIED The Google account you authorized doesn't have access to the customer ID. Make sure you authenticated with the account that manages the ad account.

OAUTH_TOKEN_EXPIRED The refresh token has expired or been revoked. Run ads auth google again to get a new one.

INVALID_CLIENT The client ID or secret is wrong. Double-check them in Google Cloud Console under APIs & Services → Credentials.

Manager account required If you don't have an MCC, omit managerId from your config. The developer token is still required — apply for one on any account that can access API Center.

On this page