trackbridge-ads-oauth

The OAuth-flow skill. Walks the five sequential steps to obtain Google Ads API credentials, in order, with a callout for each common pitfall before you hit it.

The actual button-clicking in Ads UI, Google Cloud Console, and OAuth Playground stays manual — Google’s surfaces don’t have automation hooks, and even if they did, you wouldn’t want a third party scripting your way through OAuth screens. The skill is a guide; the operator is you.

Frontmatter

name: trackbridge-ads-oauth
description: Use when setting up the Google Ads API for Trackbridge's server tracker — getting a developer token, creating an OAuth 2.0 client, obtaining a refresh token, or mapping conversionActions resource names. Covers the five-step procedure plus common pitfalls (test-vs-production token, refresh-token expiry, label-vs-resource-name confusion).

When it triggers

“Help me get the Google Ads API set up”
“I need a refresh token”
“OAuth flow for Trackbridge server tracker”
“Map my conversion actions”
Debugging Ads API rejections (DEVELOPER_TOKEN_NOT_APPROVED, USER_PERMISSION_DENIED, etc.)

Prerequisites

A Google Ads manager (MCC) account. Developer tokens are issued against managers, not customer accounts. If you only have a customer account, the skill will tell you to create an MCC and link first.
A Google Cloud project for the OAuth client. Any project will do.
A Google account with access to both, ideally a Workspace account.

What it touches

The skill writes nothing automatically. It updates .env.local and .env.example after each step once you’ve copied a value back to it:

GOOGLE_ADS_DEVELOPER_TOKEN=""
GOOGLE_ADS_CUSTOMER_ID=""
GOOGLE_OAUTH_CLIENT_ID=""
GOOGLE_OAUTH_CLIENT_SECRET=""
GOOGLE_ADS_REFRESH_TOKEN=""

It also adds entries to the conversionActions map in lib/tracker.server.ts once you’ve identified each resource name.

What it asks

Confirmation that you have a manager (MCC) account separate from the customer account.
After Step 1: paste the developer token.
After Step 2: paste the customer ID (the skill verifies it’s digits-only).
After Step 3: paste the OAuth client ID and secret.
After Step 4: paste the refresh token.
After Step 5: for each conversion action, paste the Ads API resource name and the friendly label you want to use.

Each ask is a single value. The skill doesn’t try to scrape Ads UI for you — it asks, validates the format, and writes it.

What it won’t do

Click through Google’s OAuth screens for you. Google doesn’t permit it; the operator must consent.
Decide your access tier. Test vs basic is your business decision based on whether you’re hitting a sandbox or production account.
Pick a customer account. If you have multiple linked customers, the skill asks which one and uses your answer.

The walkthrough

The five steps the skill walks (each with an embedded pitfall callout):

Step	What	Pitfall it warns about
1	Get the developer token from Ads UI → API Center	Test mode vs basic access — basic takes 1–3 business days to approve
2	Find the customer ID	The Ads UI shows it as `123-456-7890`; the API needs `1234567890`
3	Create OAuth client in Google Cloud Console	Add `https://developers.google.com/oauthplayground` as a redirect URI
4	Obtain refresh token via OAuth Playground	Personal `@gmail.com` accounts get tokens that Google revokes after 6 months — use Workspace
5	Map conversion actions	gtag conversion label and Ads API resource name are different strings; mixing them up fails on both sides

For the full prose walkthrough, see Setting up Google Ads OAuth.

Example

You: Help me set up the Google Ads API.

Claude (router → ads-oauth): Five steps. Do you have a Google Ads
manager (MCC) account, separate from your customer account?

You: Yes.

Claude: Step 1 — Sign in to your manager account at ads.google.com.
Tools & Settings → Setup → API Center. Fill in the API access form
and submit. Copy the developer token shown after submission and paste
it here.

Important: initial access is "test mode". For production traffic
you'll need basic access — request the upgrade on the same page.
1–3 business days.

You: < pastes token >

Claude: Saved to .env.local.

Step 2 — Find your customer ID. Top-right corner of the Ads UI in
your customer account, format XXX-XXX-XXXX. Paste it here, with or
without dashes — I'll strip them.

You: 123-456-7890

Claude: Saved as 1234567890. The API rejects dashes, so I always strip.

Step 3 — Create an OAuth 2.0 client in Google Cloud Console ...

Debugging Ads API rejections

The skill recognizes the common Ads API rejection codes and routes back to the relevant step:

DEVELOPER_TOKEN_NOT_APPROVED → Step 1, request basic access.
USER_PERMISSION_DENIED → Step 4, account doesn’t have access to the customer; or the conversion action belongs to a different customer.
INVALID_LOGIN_CUSTOMER_ID → MCC hierarchy needs loginCustomerId. Skill prompts for the MCC ID and adds it to the config.
INVALID_CONVERSION_ACTION_RESOURCE_NAME → Step 5, malformed resource name in conversionActions.

For the full list with response-body inspection, see the Warning catalog page.