Learn · Setup guides

Connect Google Ads API to Outloop

Last updated: August 17, 2026

Why Google Ads setup is different

Google Ads is not a "paste one API key" service. Real account access needs multiple parts:

client_id          = Google Cloud OAuth app identity
client_secret      = OAuth app secret
refresh_token      = long-lived OAuth token after consent
developer_token    = Google Ads API access token from API Center
login_customer_id  = MCC / manager account ID
customer_id        = the client ad account ID

These should not be pasted into generic API-key fields — Google Ads needs a dedicated OAuth-aware setup flow, which is how Outloop handles it.

Google Ads API: direct setup vs Outloop-managed setup

Google Ads API gives agencies powerful access, but it is not a simple API-key setup. A direct setup means the agent or workflow must handle OAuth credentials, refresh tokens, developer tokens, MCC routing, customer IDs, request headers, and tenant safety. Outloop keeps that sensitive setup host-side and gives the agent a safer way to request Google Ads actions without seeing the secrets.

Step 1: Create a dedicated Google Cloud project

Use a project reserved for API access — for example outloop-google-apis — kept separate from any website or product infrastructure projects. It holds three things: the enabled Google Ads API, the OAuth consent screen, and the OAuth client credentials.

Step 2: Enable Google Ads API

APIs & Services → Library → Google Ads API → Enable

Step 3: Create OAuth client credentials

APIs & Services → Credentials → Create credentials → OAuth client ID, application type Web application, with your own authorized origins and redirect URIs (the Outloop setup flow will tell you the exact callback URL to register).

After creation, Google shows the Client ID and — once only — the Client Secret. Do not paste these into chat. Store them only through Outloop's secure setup flow.

Step 4: Set up OAuth consent

The OAuth consent screen must be configured before anyone can authorize access. Use a neutral, accurate app name (for example Outloop Client Access) and your business email for the support and developer contacts. Do not claim official Google partnership anywhere in the consent copy.

Step 5: Get the Google Ads developer token

In the Google Ads manager account (MCC):

Tools & Settings → Setup → API Center → Developer Token

The developer token comes from Google Ads, not Google Cloud — missing this distinction is the most common setup failure. Do not paste the developer token into chat.

This token is your agency's. Google usually grants one developer token per company and states that if you use a third-party app or service, the developer of that app needs to get a token for the app. Outloop does not supply a shared developer token and you should never operate on another company's. Your agency owns the token, the Cloud project and the OAuth client; Outloop starts once those approved credentials are connected.

Step 6: Submit the API token application if needed

For full access levels, Google may require an API token application with tool-design documentation. Honest, typical answers for an agency tool:

Company type:   Agency/SEM
Use case:       Internal users only
Campaign types: Search, Performance Max, Display, Demand Gen, YouTube
Capabilities:   Account Management, Campaign Creation,
                Campaign Management, Reporting, Keyword Planning

If the tool is for your agency team and contractors, do not choose public/external users — and do not choose Account Creation unless the tool actually creates Google Ads accounts through the API.

Which Google account connects what

Access levels and what you can do today

Google grants Google Ads API access in levels, and the level you hold decides which accounts you can reach and how many operations you get per day. Knowing this changes the order you work in — you do not need the top level to run a first proof.

Explorer Access is the one most teams miss. It reaches real production accounts at a lower daily limit, which is usually enough for a read-only first proof. So apply early, then use the waiting time productively: finish the refresh token, collect client customer IDs, and map each workspace to the one account it may touch. Raise your level when real volume justifies it — applying for Standard before you need it just adds review to your critical path.

Google also runs a pilot for cloud-managed access levels, where a Google Cloud organization manages access and you can skip sending the developer token in each call. It is a pilot accepting applicants rather than a generally available feature, and it does not remove the developer token requirement — so set up the normal path above and treat that as a future option.

Shared agency app or workspace-dedicated?

Step 7: Add Google Ads access in Outloop

In Outloop, open API Keys & Access → Add Access and choose Google Ads. The panel opens on Connect in your browser, with the Cloud Console detail in the collapsed Setup details — Google Cloud OAuth client, scopes and caveats and Before you connect disclosures. Check the Google OAuth app dropdown — a saved profile supplies the app with no Client Secret to re-enter.

Google Ads still needs values the browser sign-in cannot supply — the developer token and the account IDs are not OAuth values, so you enter them on the form as before. Altogether Outloop's Google Ads setup uses six things:

• •Client ID — from the Google Cloud OAuth client (Step 3).
• •Client Secret — from the Google Cloud OAuth client. Google may show it only once; if lost, create a new secret.
• •Refresh Token — minted for you by the browser connect in Step 8. Only needed by hand if you use Advanced — manual refresh token.
• •Developer Token — from the Google Ads API Center (Step 5).
• •Login customer ID — the MCC / manager account ID, digits only, no dashes.
• •Client customer ID — the specific Google Ads account this Outloop workspace is allowed to use, digits only, no dashes.

Expected configuration:

service: google_ads
auth_type: oauth_refresh_token
token_url: https://oauth2.googleapis.com/token
client_id: <CLIENT_ID>
client_secret: <CLIENT_SECRET>
refresh_token: <REFRESH_TOKEN>
developer_token: <DEVELOPER_TOKEN>
login_customer_id: <MCC_ID>          # digits only, no dashes
customer_id: <CUSTOMER_ID>           # digits only, no dashes
base_url: https://googleads.googleapis.com

At request time the broker injects the runtime headers host-side:

Authorization: Bearer <ACCESS_TOKEN>
developer-token: <DEVELOPER_TOKEN>
login-customer-id: <MCC_ID>

The agent never sees these headers.

Step 8: Connect the account in your browser

Click Connect Google Ads in your browser. Google's own sign-in opens, you sign in with the account that has access to the MCC, and you approve the consent screen there. Outloop mints and stores the refresh token host-side — there is no token on your clipboard and none in a screenshot.

Outloop then shows Connected as the Google account you used. Check it before an agent touches a client account. Under Agents will be able to (change any time in the Access profile), practical capabilities are pre-checked and destructive ones are prefixed ⚠ and left unchecked. Click Confirm — this is the approved account.

MCC vs client customer ID

The MCC is the manager account — the account Outloop logs in through. The client customer ID is the specific Google Ads account this workspace is allowed to manage. For tenant-safe access, Outloop needs both:

login_customer_id = <MCC_ID>
customer_id       = <CUSTOMER_ID>

One MCC may access many accounts, but one Outloop workspace should only be mapped to the customer IDs it is allowed to use.

This is the whole multi-client problem in one picture. An agency has one identity — its own MCC, its own developer token, its own OAuth client — and many client accounts underneath it. Nothing about holding that credential decides which client an agent should touch on any given run. That decision has to be made somewhere, and if it is made inside the prompt, it is not really being made at all:

• →One agency MCC is connected to Outloop once.
• →Each client gets its own workspace, pinned to that client's customer ID.
• →An agent working in that workspace reads and acts on that account normally — without receiving the developer token, the client secret, or the refresh token.
• →A request pointed at a different client's customer ID is denied before any call reaches Google, so the mistake never becomes a change to a live account.
• →Both outcomes — the allow and the deny — land in a redacted local audit.

For a step-by-step version of that allow-then-deny sequence, see the multi-client walkthrough — an illustrative preview using demo data, not production evidence. The mechanism it shows is the one described here; the accounts in it are fictional.

Step 9: Map customer IDs to workspaces

This is the most important Outloop part. Example shape:

workspace_001
→ allowed Google Ads customer_id: <CUSTOMER_ID>
→ login_customer_id: <MCC_ID>

If another workspace tries to use that customer ID: deny before backend read. That is the wrong-client protection that makes one MCC safe to use across many client workspaces.

Step 10: Run a safe proof

The proof that matters is an account-scoped read against the customer ID mapped to this workspace, made under the correct MCC login context. Run it read-only:

{
  "tenant": "<WORKSPACE_ID>",
  "service": "google_ads",
  "verb": "api_bridge.request",
  "method": "POST",
  "path": "/customers/<WORKSPACE_CUSTOMER_ID>/googleAds:search",
  "body": { "query": "SELECT customer.id FROM customer LIMIT 1" }
}

Success criteria:

decision: allow / OK
HTTP 200
secret_exposed: false
the customer ID queried is this workspace's assigned customer ID
audit entry exists

Then prove the boundary in the other direction. Ask for a customer ID that is not mapped to this workspace:

decision: deny
code: RESOURCE_ID_NOT_ALLOWED
denied before any backend read
secret_exposed: false
audit entry exists

A denial here is the point, not a failure. One agency MCC can technically reach every client account under it; RESOURCE_ID_NOT_ALLOWED is Outloop refusing the wrong client before the credential is ever used. Use this workspace's assigned customer ID — do not retry with another account.

Do not mark Google Ads runtime-verified until both the allow and the deny proof succeed through Outloop.

Production readiness checklist

Do not mark Google Ads runtime-verified until all are true:

• ✓OAuth refresh works.
• ✓Developer token and login_customer_id are present.
• ✓customer_id is mapped to the workspace.
• ✓An account-scoped read on the workspace customer_id returns HTTP 200 under the correct MCC login context.
• ✓A request naming an unapproved customer_id is denied with RESOURCE_ID_NOT_ALLOWED before any backend read.
• ✓No secrets appear anywhere.

Advanced — manual refresh token

Skip this if the browser connect in Step 8 worked. It stays documented because it still works, and because some teams prefer to mint the refresh token themselves — for example when the machine running Outloop cannot open a browser session as the Google account that holds MCC access. In the Outloop panel it sits behind the collapsed Advanced — manual refresh token disclosure; paste the token there and click Save pasted refresh token.

Generate the refresh token with OAuth Playground

Google Ads needs a refresh token — the long-lived OAuth token Outloop stores locally so it can mint short-lived access tokens host-side. For manual setup, the simplest way to get one is Google's OAuth Playground.

Add OAuth Playground as a redirect URI

In Google Cloud:

APIs & Services → Credentials → OAuth 2.0 Client IDs → your Web application client

Under Authorized redirect URIs, add https://developers.google.com/oauthplayground and save. This fixes the common redirect_uri_mismatch error.

Open OAuth Playground settings

Go to https://developers.google.com/oauthplayground and click the gear icon. Set:

OAuth flow:              Server-side
OAuth endpoints:         Google
Access token location:   Authorization header w/ Bearer prefix
Access type:             Offline
Force prompt:            Consent Screen

Use your own OAuth credentials

In the same settings panel, check Use your own OAuth credentials and paste the OAuth Client ID and OAuth Client Secret from the same Google Cloud client you created for Outloop. Do not paste these values into chat, docs, tickets, screenshots, or project files.

Add the Google Ads scope

Close the settings panel. In Step 1, paste this scope:

https://www.googleapis.com/auth/adwords

Click Authorize APIs and sign in with the Google account that has access to the MCC / Google Ads accounts.

Exchange authorization code for tokens

After authorization, open Step 2 and click Exchange authorization code for tokens. Copy only the refresh_token and paste only the refresh token into Outloop.

If no refresh token is returned, the access type was not Offline or consent was not forced — see common errors. Once Outloop has the refresh token, it exchanges it for short-lived access tokens host-side; the raw refresh token never leaves your machine and the agent never sees it.

Changing the account or the credential later

What is verified vs what we don't claim

Outloop's rule is that a capability is only called verified when it was actually run here and passed. By that rule, this guide is deliberately conservative about Google Ads:

• Supported, not verified here Account-scoped reads (googleAds:search against the workspace's assigned customer ID, under the correct MCC login context): supported by the API and permitted through bridge policy. This guide gives you the exact call and success criteria — it does not publish a runtime proof of its own.
• Supported, not verified here Mutating operations under the Google Ads API: permitted through bridge policy when authorized, and audited like any other request. Not runtime-verified in this guide.
• Not claimed We publish no Google Ads customer proof and no production evidence. The multi-client walkthrough is an illustrative preview built on demo data — it shows the mechanism, not a customer result.
• Your proof, not ours The allow-and-deny pair in the checklist above is what makes your setup verified. Until both succeed on your machine, treat Google Ads as connected but unproven.

Google Ads API through Outloop vs the Google Ads MCP server

Google publishes an open-source Google Ads MCP server (github.com/googleads/google-ads-mcp), announced in October 2025. If you want an agent to ask questions about a Google Ads account, it is a reasonable thing to reach for, and it needs the same developer token and OAuth setup this guide walks you through. Google publishes no GA, beta or preview label for it, so neither do we.

Two things about it decide whether it fits agency work, and both come from Google's own documentation. First, the current release is read-only — Google's docs say it "cannot modify bids, pause campaigns, or create new assets." Second, and more important if you run many clients: the manager account is fixed per server instance, set through the GOOGLE_ADS_LOGIN_CUSTOMER_ID environment variable, while the client account is supplied per prompt — Google's own example is "How many active campaigns do I have for customer id 1234567890."

That is the honest split. The MCP server exposes the capability; which client account it lands on is decided in the conversation. Outloop decides it in policy instead — the workspace is pinned to its customer ID, and a request naming a different one is denied before any call reaches Google. Google also notes plainly that "the MCP Server will expose your data to the Agent or LLM that you connect to it." These are different jobs, and an agency can reasonably want both.

Common mistakes

• ✕Creating a plain Google Ads "API key" and expecting it to work.
• ✕Pasting only client_id and treating it as a token.
• ✕Skipping the developer token or login_customer_id.
• ✕Using the wrong MCC.
• ✕Storing the refresh token in project files.
• ✕Letting the agent choose any customer ID.

Browser sign-in troubleshooting

Google shows an account chooser

Expected. Outloop asks Google for the chooser on purpose, so a sign-in can never silently reuse whichever account your browser happened to be logged into. Pick the account that owns or can open the client's Google Ads account — which is often not the account that manages the Google Cloud project.

“Google hasn’t verified this app”

This appears because the OAuth app is your own and has not been through Google's verification. If it is your app and you trust it, expand Advanced and continue. If you do not know who owns the app, stop — that warning is doing its job, and clicking past an unknown app is not a routine step.

Which audience the app uses decides who can get that far at all. An External app in Testing only admits accounts added as Test users. An Internal app only admits accounts inside its Google Workspace organisation. For customer-facing production use, complete Google's verification rather than living in Testing.

The wrong Google account got connected

Use Connect as a different Google account on the connector. It keeps the same Client ID and Client Secret and reopens Google's chooser. The stored token is only replaced once Outloop verifies the new identity is the intended one — if it does not match, Outloop reports the mismatch and keeps the previous credential. Nothing is lost by trying.

A credential that works but sits on the wrong account is deliberately not marked runtime-verified for that workspace. Working and correct are different things.

BACKEND_AUTH_FAILED during connect

Google rejected the sign-in, so the new credential failed Outloop's safe verification. The important part: the previous credential is unchanged. Do not delete the connector, the OAuth app or the workspace as a first move. Check, in this order — that you signed in as the account that can reach the client's Google Ads account; that the account is admitted by the app's audience (a Test user on an External+Testing app); and that the API is enabled in the right Cloud project. Then try the connect again.

Reconnecting never asked for the Client ID and Secret

Expected. Disconnecting a Google Ads credential does not delete your saved Google OAuth app profile — that is a separate object, kept on purpose so later connectors do not re-enter a Client Secret. Outloop reused it. If you specifically want a different app, pick another saved profile from the Google OAuth app dropdown, or create a new one and save it alongside. This is reuse working, not a stale credential silently retained.

“Copy workspace run prompt” is not available

The Access Profile has not been saved yet. Open the Access Profile, choose the reach and the capabilities, and click Save Access Profile — the run prompt becomes available once the authorization is recorded. OAuth succeeding is not the same as the workspace being authorized, and this is the step that closes the gap.

The connection stops working after about a week

If the OAuth app's audience is External and its publishing status is still Testing, Google expires refresh tokens for that app after roughly seven days. Two honest options: publish the app to In production, or use an Internal audience if everyone signing in is inside your Google Workspace organisation. Publishing may require Google's verification review depending on the scopes the app requests — that is Google's process and its outcome and timing are not ours to promise.

Common errors and fixes

redirect_uri_mismatch

Meaning: the OAuth Playground redirect URI is missing from Google Cloud. Fix: add https://developers.google.com/oauthplayground to Authorized redirect URIs on your OAuth client (Step 7.1).

No refresh_token returned

Meaning: the consent did not use Offline access, or consent was not forced. Fix: in OAuth Playground settings set Access type: Offline and Force prompt: Consent Screen, then authorize again.

404 on /v24/v24/…

Meaning: the request path included /v24, but the bridge base URL already has it. Fix: use /customers/<ID>/googleAds:search, not /v24/customers/<ID>/googleAds:search.

Google Ads API key does not work

Meaning: a plain API key was created in Google Cloud. Fix: Google Ads account access needs OAuth Client ID + Client Secret + Refresh Token + Developer Token — a plain API key cannot manage accounts.

The Outloop value

Google gives the API access. Outloop makes it usable safely across clients:

One agency MCC can manage many client accounts.
Outloop maps each customer_id to the right workspace
and blocks wrong-client account use.

Related: AI agent API key management · wrong-client access · Meta Ads API setup · Zoho CRM setup.

Rotate or revoke access

• →Move a workspace off a client account — change the approved customer_id and save. The workspace's reach changes immediately; the credential is untouched.
• →Rotate the OAuth token — use Re-authenticate on the connector. Same Google account, fresh authorization. The developer token is unaffected.
• →Rotate the developer token — regenerate it in your manager account's API Center and update it on the connector. This is a separate credential with its own lifecycle, and rotating it affects every Google Ads connection using it.
• →Revoke everything for this connector — remove the Google Ads credential in Outloop, then revoke Outloop's access for that account at myaccount.google.com/permissions. Do both: removing the local credential does not revoke the grant at Google.
• →Off-boarding a client — also unlink the client account from your manager account in Google Ads. Revoking on your side does not end the manager-account link on theirs.

Official Google documentation

• →Google Ads API overview — prerequisites, the developer token, and the manager-account model.
• →Developer token access levels — test, basic and standard access, and what each permits.
• →Request headers and call structure — developer-token and login-customer-id.
• →Using OAuth 2.0 to access Google APIs — refresh-token behaviour, including the Testing-status expiry.

Outloop is available with guided onboarding for agency teams. Outloop is an independent tool and is not affiliated with or endorsed by Google. See the security model.