Apply for Basic API access

To use bidsmith against a production Google Ads account, you need a developer token at Basic Access tier or above. Test-access tokens (the default when you first sign up) only work against Google Ads test accounts.

The application is short, but Google requires a design document describing what your tool does. Reviewers read it carefully — vague or templated docs get rejected. bidsmith generates a fully-personalised design doc for you in two commands.

Do this first

Basic-access approval can take a few business days. If you’re new to bidsmith, start the application before chasing OAuth credentials and .bid files — your test-account setup can proceed in parallel.

Step 1 — Generate the design doc

1. Initialise the config.

   bidsmith design-doc init

   This writes design-doc.toml in the current directory — a commented template with one field per personalisation point.

2. Fill in your specifics. Open design-doc.toml in your editor. Every field marked <FILL IN …> is required. The fields reviewers focus on:

   • applicant_legal_entity — the legal name on your Google Ads account.
   • core_business, primary_customers, value_exchange — what your company actually sells, who buys it, and who pays whom for what. Google’s compliance team asks for exactly this; answer concretely, not with a mission statement.
   • why_this_tool_exists — three to five sentences describing your team’s actual workflow. Real campaign counts, real geographies, real audit/review needs. Generic boilerplate is the single biggest cause of rejection.

3. Render the HTML.

   bidsmith design-doc render

   Writes design-doc.html. Validation runs first; if any required field is still empty or still contains <FILL IN …>, the render exits non-zero and tells you which.

4. Print to PDF. Open design-doc.html in your browser, then ⌘+P (or Ctrl+P) → Save as PDF. The HTML ships with A4 print CSS; the output should look identical in any modern browser.

Step 2 — Submit the application

1. Sign in to Google Ads using the account that owns your manager (MCC) account — basic-access tokens are issued per MCC, not per Google user.

2. Open Tools → API Center. If you haven’t requested a token before, you’ll see a “Sign up” form. Otherwise, your existing token (probably in Test Access) is listed; click Apply for Basic Access.

3. Fill in Google’s application form. The free-form “How will you use the Google Ads API?” field can be a one-paragraph summary pointing at the attached PDF; the PDF has the depth.

4. Attach design-doc.pdf you just printed.

5. Submit.

Two things that trigger compliance follow-ups

• Use a corporate email address. Set the API Center contact email to an address on the applicant company’s own domain and correspond from it. Applications tied to generic mailboxes (gmail.com and the like) get a follow-up asking you to re-confirm the company’s identity from a corporate address.
• Don’t pick “Independent Developer” for an internal tool. By Google’s definition, independent developers cannot build internal tools. bidsmith is an internal tool of the company whose accounts it manages, so apply as that company — even if a contractor operates it on the company’s behalf. If people outside the company would use the tool (a client counts as an external user), that’s a different application: the tool would be classified as external.

Step 3 — Wait, and prepare for follow-ups

Approval typically takes 1–5 business days. Google may email follow-up questions. The most common ones:

Question	Where the design doc answers it
”What is your core business model? Who are your customers? What is the value exchange?”	§2 — your core_business, primary_customers, and value_exchange fields.
”Why is API access essential? Which features are critical?”	§3 — the auto-generated table mapping each workflow capability to the API service it requires.
”Who runs the tool? Is it internal or external?”	§3 — your who_uses_it_operators field plus the internal-tool classification callout.
”What endpoints do you call?”	§5 endpoint table — auto-generated from bidsmith’s source.
”How do you protect against accidental mass updates?”	§4 plan-before-apply — the explicit yes prompt is the central safety property.
”How do you store credentials?”	§7 — env vars or a mode-0600 credentials file; access tokens live in process memory only.
”Do you re-sell or expose this to other advertisers?”	§1 and §3 — single-tenant, not multi-tenant, no third-party access.

If Google asks for a revised submission, edit design-doc.toml, re-run bidsmith design-doc render, re-print the PDF, and attach the new version. The auto-generated sections stay in sync automatically.

Step 4 — Once approved

Move on to Connect to Google Ads for the OAuth setup. Your approved developer token is the value you’ll put in GOOGLE_ADS_DEVELOPER_TOKEN.

What if I only manage test accounts?

You don’t need Basic Access. Test accounts work with the default test-tier token, and bidsmith’s full feature set (plan, apply, refresh, query, pull) works against them. The application is only required for production accounts.

See also

• bidsmith design-doc — full reference for the generator command.
• Connect to Google Ads — what to set up after your token is approved.
• Authentication — what bidsmith does with your credentials at runtime.