---
name: google-business-profile-oauth-app
description: >-
  Builds on the `google-cloud-console-oauth` base skill (read that first — it
  owns the Cloud project, OAuth client, redirect URIs, secret and verification
  mechanics) and covers only what the Google Business Profile APIs add: the
  mandatory API access request that gates everything, quota pinned at 0 QPM
  until a human approves it, approval bound to a Cloud project number, the
  seven-plus-one APIs to enable, the single `business.manage` read-and-write
  scope, profile-role and Workspace permission failures, quota-increase rules,
  v4 sunset history and the no-sandbox `validateOnly` path. Use when asked for
  Google Business Profile / GMB OAuth credentials, to enable the Business
  Profile APIs, or to diagnose `0 QPM`, 429 `RESOURCE_EXHAUSTED` /
  `RATE_LIMIT_EXCEEDED`, `403 PERMISSION_DENIED` or "the API is not visible in
  the console" on a Business Profile project. For a plain Google OAuth client
  with no Business Profile scope, the base skill alone is the whole job; for
  another vendor's portal, use that vendor's skill.
---

# Google Business Profile — API access and OAuth specifics

What the **Business Profile APIs** (formerly Google My Business) add on top of an ordinary Google OAuth registration.

The expensive part of this vendor is not the OAuth client. It is that **the Business Profile APIs do not exist for
your project until a human at Google approves an access request form** (§1). Before approval your quota is **0 QPM**,
the legacy Google My Business API is not even *visible* in the Cloud console API Library, and every call fails on
quota — which looks exactly like a rate-limit bug and gets debugged as one for days. Reviews take up to **14 days**,
and the form has eligibility bars (a Business Profile verified and active 60+ days, a real website) that must be true
*before* you submit.

Two more things cost a full cycle each: enabling only some of the required APIs (§2), and filing a *quota increase*
when what you actually need is *access* — Google's docs explicitly tell you not to do that (§5).

## Built on: `google-cloud-console-oauth`

**Read `google-cloud-console-oauth` first.** It is the base skill and owns every mechanic this file does not repeat.
Without it you will be missing:

- **Project and Auth Platform setup** — creating the project, organization placement, Branding and Audience pages,
  console permissions, and the no-browser-automation click-path protocol.
- **The OAuth client** — client types, why **Web application** is the only usable one, why a service account is not
  a substitute for user consent, and reuse-vs-new-client (a new client ID re-authorizes every customer).
- **Redirect URIs** — the Unified.to callback list, exact-match / HTTPS / no-wildcard rules, `redirect_uri_mismatch`,
  propagation delay.
- **Scopes and refresh tokens** — declaring every scope on **Data Access**, the tiers, `access_type=offline` and
  `prompt=consent`, the 100-tokens-per-account cap, six-month idle expiry.
- **The one-time client secret and rotation** — stored hashed, shown in full **only at creation**; rotation is
  add-then-disable, never replace.
- **Testing vs In production, verification and hand-off** — the 7-day grant expiry in `Testing`, the user caps,
  brand/sensitive/restricted review, CASA **AL1/AL2**, and never committing the secret.

Everything below is only what Business Profile adds.

## Inputs to collect before you start

Ask in one batch, alongside the base skill's inputs. Never invent.

| Input | Notes |
| --- | --- |
| **Google account** that will own the project | Must be an owner or manager on the Business Profile cited in the request (§1) |
| **Existing Cloud project, or a new one** | Approval binds to a **project number**; a new project restarts the wait (§1) |
| **The Business Profile to cite in the request** | Verified and active 60+ days, with a website (§1) |
| **Company name, contact email, business website** | The access form asks for these (§1) |
| **Which Business Profile data you need** | Decides which APIs to enable (§2); the scope does not change (§3) |
| **Expected request volume** | Feeds the quota conversation (§5) |

## Quick Start

1. Pick the Cloud project and note its **project number** — a *new* project restarts the 14-day review (§1).
2. **Submit the access request and wait.** Nothing else works until it lands; read the quota to check status (§1).
3. Enable the seven Business Profile APIs, plus the Performance API if you need metrics (§2).
4. Create the client, redirect URIs, branding and audience — **all base skill**.
5. Declare and request the single `business.manage` scope (§3); confirm the authorizing user's role (§4).
6. Verify a real authorize → callback → refresh → read round trip against a live quota (§6).

## Platform state (verified 2026-09-20 — re-verify before trusting)

Business Profile only; the base skill carries the console's own state.

- **The Business Profile APIs are not open to the public.** Google: "GBP APIs aren't open to the public. Users have
  to request access." Approval is per **Cloud project**, granted to a Google Account that manages a qualifying
  Business Profile.
- **There is no sandbox.** Google: "There's no Sandbox environment for the Business Profile APIs." Non-mutating dry
  runs use the `validateOnly` request parameter instead. Fake or test listings are not permitted in production.
- **v4.9 is deprecated but not replaced for everything.** `localPosts`, `reviews` and `media` still live on the v4
  host; the v1 APIs (Account Management, Business Information, Performance, Verifications, Place Actions,
  Notifications, Lodging) cover the rest. Re-check the deprecation schedule before you build on a v4 endpoint —
  this family has a real sunset history (Q&A API discontinued 2025-11-03; Business Calls API and
  `locations.associate` / `locations.clearLocationAssociation` discontinued 2023-05-30; `HealthProviderAttributes`
  and `InsuranceNetworks` discontinued 2024-07-01; v4 `reportInsights` replaced by the Performance API).

## 1. Request API access — the gate that blocks everything else

**Do this first, and expect to wait.** No amount of correct OAuth configuration substitutes for it.

**The approval attaches to a Cloud project number, not to you.** So a "separate app in a different project" is not a
console decision, it is another 14-day wait at 0 QPM. Reuse the approved project unless the user explicitly accepts
restarting the review.

**Eligibility (must be true before you submit):**

- You **manage a Google Business Profile that is verified and active for 60+ days**. It may be your own office or
  headquarters, or one belonging to a client you manage.
- That business **has a website**, listed on the profile. Google wants the profile complete and current, official
  website included — an incomplete profile is a common rejection reason.

**Submitting:**

1. Copy the **project number** from the Dashboard's Project info card — not the project *ID*; the forms want the
   number.
2. Open the GBP API contact form: `https://support.google.com/business/contact/api_default`.
3. From the drop-down, choose **Application for Basic API Access** — *not* Quota Increase Request (§5).
4. Fill in company name, contact email, business website and the **project number**.
5. Submit from an email address that is listed as an **owner or manager** on that Business Profile. A request sent
   from an unrelated account is the most common silent rejection.

**Turnaround:** reviewed **within 14 days**, with a follow-up email. To check status without waiting for it, read
the Cloud console quota for the Business Profile APIs on that project — this is the documented way:

| Quota shows | Means |
| --- | --- |
| **0 QPM** | Not approved yet (or rejected) |
| **300 QPM** | Approved |

**What calling the API before approval looks like.** Not "access denied," not a `403` — a rate limit: HTTP **429 Too
Many Requests** (`RESOURCE_EXHAUSTED` / `RATE_LIMIT_EXCEEDED`), naming the metric `Requests`, the limit `Requests per
minute`, the service (e.g. `mybusinessaccountmanagement.googleapis.com`) and `consumer 'project_number:...'`. A
retry/backoff layer will chew on that forever. **Before debugging a 429 here, read the project's quota number.** If
it is 0, the project is not approved and no code change will help.

If rejected, re-check the eligibility bars above before re-applying — Google's guidance is to fix the requirements and
re-apply, not to escalate.

## 2. Enable the APIs

After approval, enable, in the Cloud console API Library for that project:

1. **Google My Business API** (v4.9 — the legacy host; still carries `localPosts`, `reviews`, `media`)
2. **My Business Account Management API** (`mybusinessaccountmanagement.googleapis.com`)
3. **My Business Business Information API** (`mybusinessbusinessinformation.googleapis.com`)
4. **My Business Lodging API**
5. **My Business Place Actions API**
6. **My Business Notifications API**
7. **My Business Verifications API**

Notes that bite:

- **Google My Business API will not appear in the Library until your account is approved.** If search does not find
  it, you are still at §1.
- **The Performance API is not in that canonical list of seven.** If you need insights/metrics, also enable
  **Business Profile Performance API** (`businessprofileperformance.googleapis.com`). Confirm its presence in the
  console rather than assuming — the setup doc and the API reference do not agree on this, and the console is the
  authority.
- Each API has its **own** quota counter. Approval grants the standard quota "for all seven APIs", but one API can
  still be the one you saturate — usually Account Management, since every connection lists accounts on setup.
- You may be prompted to enable billing and to accept per-API terms.

## 3. The single `business.manage` scope

The Business Profile APIs use **one** scope for everything:

```
https://www.googleapis.com/auth/business.manage
```

It covers read **and** write across accounts, locations, posts, reviews, media and performance — there is no
read-only variant and no per-object narrowing. Add identity scopes only if you also need to know who authorized:
`openid`, `profile`, `email`.

Two consequences worth stating to the user up front:

1. **You cannot offer a "read-only" Business Profile connection at the scope level.** Least privilege has to come
   from your own code and from the role the authorizing user holds on the profile (§4).
2. **A single broad read-and-write scope is what verification scrutinizes.** Read the tier label the console puts on
   `business.manage` in *your* project rather than assuming, and have the justification ready: which endpoints you
   call, and that nothing narrower is published.

There is no API-key path for this family — every request touching private user data needs an OAuth 2.0 token.

**Product fact — as of 2026-09-20, Unified.to's Google Business Profile connector requests `openid`, `profile`,
`email` and `https://www.googleapis.com/auth/business.manage` for every supported operation** (posts read and write,
profiles read, reviews read and write, insights read) — one scope set, identical across objects. It spans the v4 host
plus the Account Management, Business Information and Performance v1 hosts, so all four must be enabled on whichever
project's client ID is in play. It also supports a Google **service-account** token path as an alternative to the user
OAuth flow, and **ships with a shared, platform-owned Google OAuth client by default** — so unless a customer supplies
their own client, calls hit the *platform's* project quota and a quota increase on the customer's own project changes
nothing (§5). Confirm this with the connector's owner; connector configuration changes without notice.

## 4. Who is allowed to authorize

Scope is not the limit here — the authorizing person's role on the profile is.

- The account must be an **owner or manager** of the Business Profile. Managers have nearly the same access as owners
  but cannot add or remove users. The authorizing end user's role caps what their token can do, and **no scope raises
  it**. A `403` affecting exactly one customer is usually this.
- Organizations / agency accounts are created from the Business Profile help center, not from Cloud.
- **Google Workspace accounts** — Business Profile must be *turned on* for the account in the Workspace organization.
  If it is off, the APIs return **`403 PERMISSION_DENIED`** no matter how correct the project, scope and client are.
  This is distinct from the base skill's Workspace admin API-controls case, and the fix is a different admin toggle.

## 5. Quota — and the request that is *not* the access request

Once approved, the documented standard limits are:

| Limit | Value |
| --- | --- |
| Default requests | **300 QPM** per API |
| Create Location | 300 QPD |
| SearchGoogleLocation | 300 QPD |
| Update Location | 10,000 QPD |
| Edits | **10 per minute per Business Profile — cannot be increased** |

Exceeding a quota returns **429 Too Many Requests** (`RESOURCE_EXHAUSTED` for gRPC) — the same shape as the
pre-approval failure in §1, which is why the quota number is the first thing to read.

**If your quota reads 0, do not file a quota increase.** Google says so explicitly: quota 0 means access was never
granted, and the fix is the access request form in §1. The two requests go through the *same* contact form under
different drop-down options, so picking the wrong one is easy — and it costs another full review cycle, because the
quota team will simply tell you to go and apply for access.

To request a genuine increase, use that contact form with **Quota Increase Request** selected, and supply company
name, contact email and project number. Increases are typically **denied** when: the app does not consistently reach
its current QPM, average usage is under **50%** of the current limit, or traffic is **spiky** rather than smoothly
distributed. That last one is a design instruction — smooth and cache before you ask.

Quota is **per project**. On a multi-tenant platform using one shared OAuth client, every customer's calls land on
the *platform's* counter, and Account Management (hit by every connection to list accounts) saturates first. Levers in
order: drop redundant account-listing calls, cache account and location resolution, back off honoring `retryDelay` /
`Retry-After`, and only then ask for more. A customer needing more headroom than the shared project can give needs
their own approved project and client — meaning they go through §1 themselves, 14-day wait included.

## 6. Verify end-to-end

On top of the base skill's round-trip checks:

1. Confirm the quota reads **300 QPM**, not 0, before concluding anything about a failed call.
2. Authorize from a Google account that manages a **different** Business Profile than the one you cited in the access
   request — approval is per project, not per profile, and this proves it.
3. Make a read call — listing accounts on the Account Management host is the natural smoke test.
4. Exercise a mutating path with **`validateOnly`** rather than looking for a sandbox; there isn't one, and test
   listings are not permitted in production.
5. If the app is still in `Testing`, re-test after **8 days** or publish first — the base skill's 7-day grant expiry
   presents here as a Business Profile connector with a mysterious weekly outage.

| Symptom | Cause |
| --- | --- |
| Google My Business API missing from the API Library | Project/account not approved — §1, not a console bug |
| 429 `RATE_LIMIT_EXCEEDED` on the very first call, quota shows 0 QPM | Not approved. Submit the access form; do **not** file a quota increase (§5) |
| 429 later, quota shows 300 QPM | Real quota exhaustion — usually shared-project Account Management calls (§5) |
| `403 PERMISSION_DENIED` on a Workspace account | Business Profile turned off for that account in the Workspace org (§4) |
| `403` on one customer only | The authorizing user is not an owner/manager of that profile (§4) |
| Edits throttle at 10/minute on one profile and never improve | Per-profile edit limit; cannot be raised (§5) |
| A previously working endpoint 404s | v4 endpoint sunset — check the deprecation schedule (References) |

**Add to the base skill's hand-off:** the Cloud project **number**, the access-approval state with the quota reading
that proves it, which APIs are enabled (including whether the Performance API is on), and the date of anything still
under review.

## Stop and ask

Beyond the base skill's list, hand back to a human when: the access request is pending or rejected (there is nothing
to configure around it — report the state and the date); the eligibility bars are not met and someone suggests citing
a profile they do not manage; the form asks for company, volume, compliance or business-justification claims you
cannot source from the user; the fix requires a customer to create and get approval for their *own* Cloud project; a
change would move the integration to a different Cloud project and restart the 14-day review; or a needed endpoint
exists only on the deprecated v4 host and the sunset schedule is unclear.

## References

Business Profile only — the base skill carries the generic Google OAuth references. Every URL verified to resolve on
2026-09-20.

- Business Profile APIs overview — https://developers.google.com/my-business/content/overview
- Prerequisites and access request — https://developers.google.com/my-business/content/prereqs
- Basic setup (enable APIs, OAuth client, scope) — https://developers.google.com/my-business/content/basic-setup
- Quota limits — https://developers.google.com/my-business/content/limits
- FAQ (14-day review, seven APIs, quota, no sandbox) — https://developers.google.com/my-business/content/faq
- API policies — https://developers.google.com/my-business/content/policies
- Deprecation schedule — https://developers.google.com/my-business/content/sunset-dates
- Change log — https://developers.google.com/my-business/content/change-log
- Latest updates — https://developers.google.com/my-business/content/latest-updates
- API reference overview — https://developers.google.com/my-business/ref_overview
- Google My Business API v4.9 reference (legacy) — https://developers.google.com/my-business/reference/rest
- `accounts.locations.localPosts` (v4) — https://developers.google.com/my-business/reference/rest/v4/accounts.locations.localPosts
- `accounts.locations.reviews` (v4) — https://developers.google.com/my-business/reference/rest/v4/accounts.locations.reviews
- `accounts.locations.media` (v4) — https://developers.google.com/my-business/reference/rest/v4/accounts.locations.media
- Account Management API — https://developers.google.com/my-business/reference/accountmanagement/rest
- Business Information API — https://developers.google.com/my-business/reference/businessinformation/rest
- Performance API — https://developers.google.com/my-business/reference/performance/rest
- GBP API contact form (access *and* quota requests) — https://support.google.com/business/contact/api_default
- Verify your business on Google — https://support.google.com/business/answer/7107242
- Add or claim your Business Profile — https://support.google.com/business/answer/2911778
- Business Profile owners and managers — https://support.google.com/business/answer/3403100
- Manage agency organizations — https://support.google.com/business/answer/7663063