Connect to Google Ads

The fastest way to connect bidsmith to Google Ads is:

bidsmith auth login

It opens your browser, you click Allow, and bidsmith saves the sign-in to ~/.bidsmith/credentials.toml (locked to your user, file mode 0600). This page explains what you need first, the one-step worker flow, and the environment-variable alternative for CI.

What you need

Google Ads asks for four separate things. The good news: most of them are set up once per agency, not once per person.

What	Who provides it	Per person?
Your Google sign-in	The browser, during auth login	Yes — but it’s one click
Developer token	Your agency’s manager account (MCC)	No — one shared token for the whole agency
Manager account ID (MCC)	Your agency	No — same for everyone in the agency
OAuth client	Your agency’s Google Cloud project (see below)	No — created once
Customer ID	Per Google Ads account you manage	Goes in each project’s provider block, not here

If someone at your agency has already done the one-time setup, skip to I was handed a team profile. If you’re the one setting it up, start at Set up the agency once.

Why an OAuth client?

An OAuth client is what lets the browser sign-in work. bidsmith will ship a built-in one (so you’d need nothing but a browser), but it’s still going through Google’s app-verification review. Until that lands, your agency supplies one — created once, shared by everyone.

I was handed a team profile

If a colleague ran bidsmith auth profile --with-client, they have a ready-to-run command for you. It looks like:

bidsmith auth login --developer-token AbC… --login-customer-id 1234567890 \
  --client-id 123-abc.apps.googleusercontent.com --client-secret GOCSPX-…

1. Paste that command into your terminal and run it.
2. Your browser opens. Sign in with your own Google account (the one your agency invited to the Google Ads accounts) and click Allow.
3. bidsmith prints the accounts you can manage and saves everything. Done.

That’s the whole worker flow — one paste, one browser click.

Set up the agency once

Two one-time tasks, done by whoever administers the agency’s API access.

1. Get a developer token. In Google Ads → Tools → API Center, apply for a developer token. New tokens start in test access (fine against a test account); a production account needs basic access, and bidsmith generates the design document Google asks for with that application — see Apply for Basic API access.

2. Create an OAuth client. In Google Cloud Console, enable the Google Ads API, configure the OAuth consent screen with the scope https://www.googleapis.com/auth/adwords, and create a credential of type Desktop app. Note the client ID and secret.

3. Sign in and share. Run bidsmith auth login with your client and developer token, then hand the result to teammates:

   bidsmith auth login \
     --client-id 123-abc.apps.googleusercontent.com \
     --client-secret GOCSPX-xxxxxxxx \
     --developer-token AbC1DeFg2HiJk-LMNo3PqRs \
     --login-customer-id 1234567890
   
   # then print a ready-to-run command for each teammate:
   bidsmith auth profile --with-client

The profile contains a secret

auth profile includes the developer token (and, with --with-client, the OAuth client secret). Share it through a password manager or another trusted channel — not a public Slack channel or email.

Verify the connection

bidsmith auth status

Expected output:

Credentials (env var > ~/.bidsmith/credentials.toml > built-in):
  client_id         : 123-abc.apps.googleusercontent.com
  developer_token   : set (AbC1De…, 23 chars)
  login_customer_id : 1234567890
  ...

✓ Google sign-in works (access token valid for 3599s).
✓ 3 account(s) reachable:
  123-456-7890
  234-567-8901
  345-678-9012

If you see your accounts listed, you’re connected.

Pick which account to manage

auth login connects you to Google Ads; it doesn’t decide which account a project edits. That lives in each project’s provider block, so one login can manage many accounts:

provider "google_ads" {
  customer_id = "1234567890"   # the account this folder manages
}

Use one of the 10-digit IDs auth status printed (drop the dashes).

Managing several accounts at once? Put the routing in a per-folder bidsmith.toml instead, so your .bid files stay account-agnostic and one sign-in covers them all.

The environment-variable way (CI and power users)

auth login writes a file; CI usually can’t do a browser sign-in. For automation, set the same values as environment variables instead — an env var always takes precedence over the saved file.

zsh / bash (macOS, Linux)

export GOOGLE_ADS_DEVELOPER_TOKEN="aBc1DeFg2HiJk-LMNo3PqRs"
export GOOGLE_ADS_CLIENT_ID="123456789-abc...apps.googleusercontent.com"
export GOOGLE_ADS_CLIENT_SECRET="GOCSPX-xxxxxxxxxxxxxxxx"
export GOOGLE_ADS_REFRESH_TOKEN="1//09xxxxxxxxxxxxxxxxxxx"
export GOOGLE_ADS_CUSTOMER_ID="1234567890"
# export GOOGLE_ADS_LOGIN_CUSTOMER_ID="9876543210"  # uncomment if needed

Nushell

$env.GOOGLE_ADS_DEVELOPER_TOKEN = "aBc1DeFg2HiJk-LMNo3PqRs"
$env.GOOGLE_ADS_CLIENT_ID = "123456789-abc...apps.googleusercontent.com"
$env.GOOGLE_ADS_CLIENT_SECRET = "GOCSPX-xxxxxxxxxxxxxxxx"
$env.GOOGLE_ADS_REFRESH_TOKEN = "1//09xxxxxxxxxxxxxxxxxxx"
$env.GOOGLE_ADS_CUSTOMER_ID = "1234567890"

The refresh token here is minted the old way — via Google’s OAuth Playground using your own OAuth credentials. For laptops, prefer auth login. More on the runtime model in Authentication.

Troubleshooting

Symptom	Likely cause
no OAuth client to sign in with	This build has no bundled client yet. Pass --client-id / --client-secret (your agency’s Desktop-app client).
Google sign-in was denied	You clicked Cancel, or the consent screen’s scope isn’t adwords. Re-run and Allow.
developer token is not approved	Token is still in test-access mode. Use a test account, or apply for basic access via the API Center.
the saved Google sign-in was created with a different OAuth client	A GOOGLE_ADS_CLIENT_ID env var now points at a different client than the one you logged in with. Unset it, or run bidsmith auth login again.
PERMISSION_DENIED or customer not found	Set the manager account: --login-customer-id (or GOOGLE_ADS_LOGIN_CUSTOMER_ID).
command not found: bidsmith	Re-check the install page.
Anything mentioning a retired API version	Set BIDSMITH_API_VERSION to the current version (defaults to v25).

Next

Your first 10 minutes — clone a starter repo, run plan and apply for the first time.