Google Ads API — Tool Design Document
AZX Digital · Internal reporting and campaign management integration · Version 2.0 · September 2026
| Company | AZX Digital — performance marketing agency, Brazil |
|---|---|
| Primary website | https://azxdigital.com · application page: https://azxdigital.com/app |
| Google Ads manager account (MCC) | 294-208-1233 |
| Accounts in scope | Client accounts linked to the MCC, plus client accounts where we hold direct user access, plus our own agency account |
| Google Cloud project | azx-digital · project number 389009356121 |
| API contact | lucasrafael@azxdigital.com |
| Access requested | Basic Access |
| Capabilities requested | Reporting · Keyword Planning Services · Campaign Management · Campaign Creation |
| Not requested | Account Creation · Account Management · App Conversion Tracking and Remarketing API |
1. Business model
AZX Digital is a Brazilian performance marketing agency. We manage Google Ads accounts on behalf of our clients in two ways: most client accounts are linked to our Google Ads manager account (MCC 294-208-1233), and a few are accounts where the client granted us direct user access instead of linking. In both cases access is granted with the client's consent, and our team plans, operates and reports on their campaigns as a paid service. We also use the same tool for AZX Digital's own campaigns when we advertise our services. Our revenue comes from agency retainers paid by those clients; we do not resell API access, we do not charge for the tool and the tool itself is not a product.
As of this application, six active advertiser accounts are linked to our manager account and three more are operated through direct user access, all of them clients under an agency contract.
2. Tool overview and intended audience
The tool described here is an internal integration used exclusively by AZX Digital staff. It is not a public product, it is not sold or licensed, it has no external users and it is not offered to third parties. Its purpose is to replace repetitive manual work in the Google Ads UI with programmatic reporting, keyword planning and campaign operations for the accounts we already administer.
Audience: internal users only (agency staff, including contractors bound by the same agreements).
3. Google Ads API services used
| GoogleAdsService | GAQL queries for performance reports across campaigns, ad groups, ads, keywords and search terms of the managed accounts. Reporting. |
|---|---|
| KeywordPlanIdeaService RecommendationService | Keyword ideas and search-volume estimates used to plan Search campaigns for the managed accounts, and Google's own optimization recommendations, reviewed by an operator before being applied or dismissed. Keyword Planning Services / Researching keywords and recommendations. |
| CampaignService CampaignBudgetService | Read and update status and daily budget of the campaigns we operate. Campaign Management. |
| AdGroupService AdGroupAdService AdGroupCriterionService | Create and maintain Search campaigns, responsive search ads and keywords in the managed accounts. Campaign Creation. |
Out of scope: account creation and account administration, the App Conversion Tracking and Remarketing API, reselling API access and serving third parties.
4. Architecture
Operator workstation (AZX staff) Google
+-----------------------------+ +---------------------------+
| CLI / natural-language front | HTTPS | googleads.googleapis.com |
| + local MCP clients |=========>| Google Ads API v25 |
| - reporting client (read) | OAuth | |
| - management client (write) | 2.0 | login-customer-id: |
| - local audit log + cache | | 294-208-1233 (our MCC) |
+-----------------------------+ +---------------------------+
local disk only
(refresh token 600, no server)
The integration runs locally on agency workstations. There is no public server, no hosted multi-tenant service and no storage of Google Ads data outside the operator's machine. We use two self-hosted open-source clients: Google's official google-ads-mcp for read-only reporting and the open-source mcp-google-ads project for campaign management, both operated under our own credentials. These are open-source client libraries that we install and run ourselves on our own machines. They are not a third-party product or service: no outside party operates the tool, and the developer token is never shared with, transmitted to, or used by anyone outside AZX Digital.
5. Authentication and credentials
| OAuth 2.0 | Authorization code flow with a Desktop-app OAuth client from our own Google Cloud project (azx-digital). Refresh token stored locally with file permissions 600; scope limited to https://www.googleapis.com/auth/adwords. |
|---|---|
| Developer token | Issued to our MCC. Sent only in the developer-token header to googleads.googleapis.com. Never shared with clients or third parties. |
| Account context | login-customer-id is always set to our MCC; requests target only client accounts linked to that MCC. |
| Secret handling | Credentials live in local dot-files owned by the operator. They are never committed to repositories, embedded in websites or shared with clients. |
6. Safety controls for write operations
- Human review: every mutation follows a draft, review and confirm flow; dry-run is enforced by default.
- Paused by default: campaigns and ads are created in PAUSED status and activated manually after review.
- Budget guardrails: configurable maximum daily budget per campaign and maximum bid increase percentage.
- Audit log: all mutations are appended to a local audit log with timestamp and payload.
- Read-only mode: the reporting client has no write capability at all.
7. API usage and quota behavior
Request volume is low: individual GAQL report queries and small mutate batches, initiated by a human operator for a small portfolio of managed accounts. We respect rate limits with retry and exponential backoff on RESOURCE_EXHAUSTED, use page sizes within API defaults, and cache report results locally to avoid repeated identical queries. Expected volume is well under a few thousand operations per day.
8. Data handling and privacy
Report data is used to build performance summaries for internal analysis and client reporting. We do not collect end-user personal data through this tool, we do not use the App Conversion Tracking and Remarketing API, and we do not share Google Ads data with third parties. Data at rest remains on agency-controlled machines. Our handling of information received from Google APIs follows the Google API Services User Data Policy, including the Limited Use requirements.
9. Contact
API contact: lucasrafael@azxdigital.com · Company: AZX Digital · Website: https://azxdigital.com · Manager account (MCC): 294-208-1233 · Google Cloud project: azx-digital (389009356121)