Connect to Google Ads

bidsmith reads five environment variables to talk to the Google Ads API:

Variable	What it is
GOOGLE_ADS_DEVELOPER_TOKEN	A token from your Google Ads manager account that authorizes API access.
GOOGLE_ADS_CLIENT_ID	The OAuth client ID — identifies bidsmith as an “app” to Google.
GOOGLE_ADS_CLIENT_SECRET	The OAuth client secret — paired with the client ID.
GOOGLE_ADS_REFRESH_TOKEN	A long-lived token bidsmith exchanges for short-lived access tokens on every run.
GOOGLE_ADS_CUSTOMER_ID	The numeric ID of the Google Ads account you’re managing (10 digits, no dashes).

Optionally GOOGLE_ADS_LOGIN_CUSTOMER_ID — set to your manager account ID if you’re managing a sub-account via an MCC.

You set these once. Total setup time: ≈ 15 minutes the first time.

Auth helper coming soon

A bidsmith auth subcommand that automates this entire flow is on the roadmap. Until then, follow Google’s docs to obtain the four credentials, then come back here for the env-var setup and smoke test.

Step 1 — Obtain the four credentials

Google’s docs are the canonical walkthrough for each piece. Open them in order:

1. Developer token → Obtain a developer token. Apply via Google Ads → Tools → API Center. New tokens start in test access mode, which is fine for trying bidsmith against a test account. For a production account you need basic access — bidsmith ships a generator for the design document Google requires with that application; see Apply for Basic API access.

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

3. Refresh token → Generate a refresh token via the OAuth Playground. Use your own OAuth credentials in the Playground settings (gear icon → “Use your own OAuth credentials”), authorize the adwords scope, and copy the refresh token from the response. Treat it like a password.

4. Customer ID — the 10-digit number in the top-right of the Google Ads UI (formatted as 123-456-7890). bidsmith expects it without dashes: 1234567890.

Step 2 — Save them as env vars

zsh / bash (macOS, Linux)

Add to ~/.zshrc (zsh, default on modern macOS) or ~/.bashrc (bash, default on most Linux distros):

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

Open a new terminal window so the changes take effect, or run source ~/.zshrc.

Tip

Many teams keep a .envrc file in the bidsmith-config repo and use direnv to load it automatically when you cd into the folder. Don’t commit .envrc to Git — add it to .gitignore.

Nushell

Add to your Nushell environment file ($nu.env-path):

$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"

Open a new shell or source the env file.

Step 3 — Smoke test

Confirm bidsmith can authenticate with what you just configured:

bidsmith plan --whoami

Expected output:

Refresh token exchanged successfully.
Access token expires in 3599 seconds.
Customer ID: 1234567890

If you see that, you’re done. Skip to the first tutorial.

Troubleshooting

Symptom	Likely cause
developer token is not approved	Token is still in test-access mode. Either use a test account, or apply for basic access via the API Center.
invalid_grant	Refresh token is wrong, revoked, or expired. Re-do step 1.3.
PERMISSION_DENIED or customer not found	Set GOOGLE_ADS_LOGIN_CUSTOMER_ID to your manager account ID.
command not found: bidsmith	Re-check the install page. Open a new terminal so shell config changes take effect.
Anything mentioning a retired API version	Set BIDSMITH_API_VERSION to the current version (defaults to v22).

Next

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