Google Business return addresses — list, register and remove

The return addresses are the allow-list of where connect sessions may send an end user’s browser afterwards. A session whose redirectUrl is not inside one of them is refused (400 gmb_redirect_not_allowed) and creates nothing. The guide Connect your clients’ Google Business Profiles explains where they fit. These endpoints need a package that includes the connector (402 gmb_plan_required otherwise).

The rules for an address

An address is checked, then stored as origin plus path with no trailing slash (https://app.example.com/google/ is stored as https://app.example.com/google).

Rule	Detail
Scheme	https only. Plain http is accepted only for localhost, 127.0.0.1 and [::1]. Every other scheme (javascript:, data:, …) is refused
Credentials	No username or password in the URL
Fragment	No #fragment
Query	A registered address has no query string (a session’s redirectUrl may have one)
Length	An absolute URL of at most 2,000 characters

A refusal is 400 gmb_redirect_not_allowed. Registering an address already on the list is 409 gmb_redirect_exists.

How a session’s redirectUrl is matched. Same origin (scheme, host and port), and a path that is equal to the registered path or below it on a segment boundary. With https://app.example.com/connect registered:

redirectUrl	Allowed?
https://app.example.com/connect	Yes
https://app.example.com/connect/done?ref=7	Yes
https://app.example.com/connected	No (not on a / boundary)
https://app.example.com/	No (above it)
https://app.example.com.evil.test/connect	No (another host)
http://localhost/connect	No (another origin)

Register the narrowest address you need.

GET /gmb/redirect-uris

Scope	read or gmb
Auth	Authorization: Bearer mk_live_…

curl https://app.maukirim.com/api/v1/gmb/redirect-uris -H "Authorization: Bearer mk_live_…"

{
  "ok": true,
  "redirectUris": [
    { "id": "gmr_4k9s2x7q1d", "uri": "https://app.example.com/google/return", "createdAt": "2026-10-14T02:00:00.000Z" }
  ]
}

Oldest first, no paging. No Google call, no budget.

---

POST /gmb/redirect-uris

Registers an address.

Scope	gmb
Body	application/json: { "uri": "https://app.example.com/google/return" }

curl -X POST https://app.maukirim.com/api/v1/gmb/redirect-uris \
  -H "Authorization: Bearer mk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "uri": "https://app.example.com/google/return" }'

const response = await fetch("https://app.maukirim.com/api/v1/gmb/redirect-uris", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MAUKIRIM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ uri: "https://app.example.com/google/return" }),
})
const { redirectUri } = await response.json()

$curl = curl_init('https://app.maukirim.com/api/v1/gmb/redirect-uris');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('MAUKIRIM_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['uri' => 'https://app.example.com/google/return']),
    CURLOPT_RETURNTRANSFER => true,
]);
$redirectUri = json_decode(curl_exec($curl), true)['redirectUri'];

201 Created:

{
  "ok": true,
  "redirectUri": { "id": "gmr_4k9s2x7q1d", "uri": "https://app.example.com/google/return", "createdAt": "2026-10-14T02:00:00.000Z" }
}

uri in the response is the normalised form that was stored.

---

DELETE /gmb/redirect-uris/{id}

Removes one address. New sessions for it are refused from then on; sessions already created keep the address they were created with and still end there.

Scope	gmb
Path	id — the return address id (gmr_…)

curl -X DELETE https://app.maukirim.com/api/v1/gmb/redirect-uris/gmr_4k9s2x7q1d -H "Authorization: Bearer mk_live_…"

{ "ok": true }

Errors

HTTP	Code	Condition
400	gmb_redirect_not_allowed	(POST) The address is not https (or localhost http), has credentials, a fragment or a query, is not absolute, or is longer than 2,000 characters
401	api_key_invalid / api_key_revoked / api_key_expired
402	gmb_plan_required	The package does not include the connector
403	api_key_scope_denied	A read needs read or gmb; POST and DELETE need gmb
404	not_found	(DELETE) No return address with that id on this account
409	gmb_redirect_exists	(POST) That address is already registered