Setting up Google Ads OAuth

The server tracker needs five Google credentials to talk to the Ads API. This is the highest-friction part of integrating Trackbridge — the values are scattered across two products (Ads UI, Google Cloud Console) and one helper tool (OAuth Playground), and Google’s own documentation is split across half a dozen pages. This guide walks the entire path in order.

What you’ll end up with:

GOOGLE_ADS_DEVELOPER_TOKEN=""        # Step 1
GOOGLE_ADS_CUSTOMER_ID="1234567890"  # Step 2 — digits only
GOOGLE_OAUTH_CLIENT_ID=""            # Step 3
GOOGLE_OAUTH_CLIENT_SECRET=""        # Step 3
GOOGLE_ADS_REFRESH_TOKEN=""          # Step 4

Plan for an hour the first time through. Most of it is waiting for token approval and clicking through OAuth flows.

Prerequisites

A Google Ads manager (MCC) account — the developer token is requested against the manager, not the customer account. If you only have a customer account, create an MCC and link your customer account to it.
A Google Cloud project — any project will do; you’ll only use OAuth, not other Cloud services.
A Google account that has access to both, ideally a Workspace account (you@yourcompany.com). Personal @gmail.com works for development but produces refresh tokens Google revokes more aggressively.

Step 1: Get the developer token

Sign in to your manager account at ads.google.com.
Tools & Settings (wrench icon) → Setup → API Center.
Fill in the API access form (company, intended use, contact email). Submit.
The page now shows your developer token. Copy it.

GOOGLE_ADS_DEVELOPER_TOKEN="<copied value>"

About access levels. Initial issuance is test mode — the token works only against test accounts (created via the manager UI). Production traffic requires basic access, which is a separate request on the same API Center page; approval typically takes 1–3 business days. Higher-volume traffic later requires standard access.

For early integration: do steps 2–5 with whatever access level you have. If you’re working against a real customer account in development, request basic access immediately so it’s ready when you ship.

Step 2: Find your customer ID

In your customer account (top-right corner of the Ads UI), the customer ID appears as XXX-XXX-XXXX.

GOOGLE_ADS_CUSTOMER_ID="1234567890"

No dashes. The Ads API rejects 123-456-7890 with a confusing error. Trackbridge does not strip them for you.

Step 3: Create an OAuth 2.0 client

Open console.cloud.google.com, select (or create) a project.
APIs & Services → OAuth consent screen.
Configure as External (unless your project lives inside a Workspace).
Add scope: https://www.googleapis.com/auth/adwords.
Save and continue through the wizard. You don’t need to publish the app for development — “Testing” mode lets you authorize Google accounts you list as test users.
Credentials → Create credentials → OAuth client ID → Application type: Web application.
Add authorized redirect URI: https://developers.google.com/oauthplayground (you’ll use OAuth Playground in the next step).
Save. Copy the client ID and client secret.

GOOGLE_OAUTH_CLIENT_ID="<client id>.apps.googleusercontent.com"
GOOGLE_OAUTH_CLIENT_SECRET="<client secret>"

Step 4: Obtain a refresh token via OAuth Playground

Open developers.google.com/oauthplayground.
Click the gear icon (top-right) → Use your own OAuth credentials. Paste the client ID and client secret from Step 3. Close the gear panel.
In the left scope picker, paste https://www.googleapis.com/auth/adwords into the input below the scope list, then click Authorize APIs.
Sign in with the Google account that has access to the manager and customer accounts.
Approve the consent screen. (If you’re in “Testing” mode and your account isn’t listed as a test user, add it under OAuth consent screen → Test users.)
Back on Playground, click Exchange authorization code for tokens.
Copy the refresh token (the long one, not the access token).

GOOGLE_ADS_REFRESH_TOKEN="<refresh token>"

The access token shown alongside is short-lived; the SDK refreshes it automatically using the refresh token.

Workspace vs personal accounts. Refresh tokens issued to personal @gmail.com accounts are revoked by Google after 6 months of inactivity, on password change, on sign-out-everywhere, and when per-app limits are hit. Refresh tokens from Google Workspace accounts are stable. Use Workspace for production; reissue from Playground if a personal-account token gets revoked.

Step 5: Map your conversion actions

For every conversion you’ll fire from the server, you need its Ads API resource name.

In the customer account: Tools & Settings → Measurement → Conversions.
Click into the conversion action.
Open the Tag setup or API view. The resource name is in the format:

customers/{customerId}/conversionActions/{actionId}

In your server tracker, map your friendly label (the same string you pass as label to trackConversion) to the resource name:

ads: {
  conversionActions: {
    purchase: 'customers/1234567890/conversionActions/9876543210',
    signup: 'customers/1234567890/conversionActions/1122334455',
  },
},

For the full conversion-action / gtag-label distinction, see Mapping conversion actions.

Common rejections

These are the Ads API errors you’ll see when something is off:

DEVELOPER_TOKEN_NOT_APPROVED — token is in test mode; firing against a production customer account. Either upgrade access or use a test account.
USER_PERMISSION_DENIED — the account holding the refresh token doesn’t have access to the customer account, or the conversion action belongs to a different customer than customerId. Verify both in the Ads UI.
INVALID_LOGIN_CUSTOMER_ID — your MCC hierarchy requires loginCustomerId to be passed alongside customerId. Set ads.loginCustomerId to the MCC ID (digits only).
INVALID_CUSTOMER_ID — almost always dashes in the customer ID. Strip them.
INVALID_CONVERSION_ACTION_RESOURCE_NAME — the value in conversionActions is malformed. The format is exactly customers/{cid}/conversionActions/{aid}.

With debug: true on createServerTracker, these errors land in your console with the full response body.