Jonathon's AI Wiki

Reconnect Broken Marketplace Apps

4 min read

Source: ai-research/ghl-2026-05-01/support-solutions-articles-155000003717-how-to-reconnect-broken-marketplace-apps.md

When an OAuth access or refresh token gets lost or invalidated — whether from a HighLevel-side incident or a developer-side mistake — the Reconnect API issues a fresh authorization code that flows through the standard Get Access Token endpoint to recover a working token pair. The point of the API is recovery without forcing the end user back through an OAuth consent screen. Two payload variants exist: one for sub-account connections, one for agency connections.

Key Takeaways

  • Endpoint: POST https://services.leadconnectorhq.com/oauth/reconnect with Content-Type: application/json.
  • Two scopes of reconnection. Sub-account reconnections carry locationId; agency reconnections carry companyId. All variants require the app’s clientKey and clientSecret.
  • Returns an authorization code, not a token. The response gives back an authorizationCode and an expiresAt timestamp. Feed the code into the standard Get Access Token API (OAuth Authorization Code flow) to mint a new access/refresh token pair.
  • No user prompt required. This is the load-bearing benefit — users do not have to re-grant consent or re-install the app. The reconnection happens entirely via developer credentials.
  • Recovery scenarios. HighLevel-side incidents that invalidate tokens, developer-side mistakes (deleted token store, deploy migration, accidental refresh-token rotation), or any case where you have proof of prior installation but no working tokens.
  • Each authorization code has a short expiry (expiresAt in the response). Exchange it promptly via the Get Access Token endpoint before it expires.
  • Trace ID returned for support escalation. The response includes a traceId field — capture it in logs in case you need to file a ticket with the HighLevel API team.

Endpoint Reference

Sub-Account App Connections

curl --location 'https://services.leadconnectorhq.com/oauth/reconnect' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "",
    "clientSecret": "",
    "locationId": ""
  }'

Agency Connections

curl --location 'https://services.leadconnectorhq.com/oauth/reconnect' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientKey": "",
    "clientSecret": "",
    "companyId": ""
  }'

Response

{
  "authorizationCode": "",
  "expiresAt": "2024-10-08T13:35:43.887Z",
  "traceId": "trace-ID-ref"
}

Recovery Workflow

  1. Detect that an installation’s tokens are invalid (refresh attempt fails with invalid_grant, or the token store entry is missing).
  2. Look up the locationId (sub-account) or companyId (agency) tied to the broken installation.
  3. POST to /oauth/reconnect with clientKey, clientSecret, and the appropriate ID.
  4. Capture the authorizationCode from the response.
  5. Exchange the authorization code for a new access/refresh token pair via the Get Access Token API.
  6. Store the new tokens in your token store, replacing the broken entry.
  7. Resume normal operation — no user-facing reconnect prompt required.

Use Cases

  • Incident recovery. HighLevel publishes a notice that a subset of tokens were rotated; bulk-reconnect every affected installation without paging end users.
  • Developer error. A deploy migration accidentally drops the token database; reconnect every known installation from the canonical record of locationId / companyId IDs.
  • Refresh-token rotation bugs. A bug in your token refresh logic invalidates the refresh token; reconnect to recover without sending users a “please reinstall” email.
  • Cold migration. Moving a Marketplace app between hosting environments where the token store doesn’t transfer cleanly.

Try It

  1. Pick a single test installation in a development sub-account and intentionally invalidate its refresh token (e.g., delete the token store row).
  2. Confirm the next API call against that installation fails with an auth error.
  3. Run the sub-account reconnect curl with that location’s locationId and your app credentials.
  4. Capture the authorizationCode from the response and exchange it via the Get Access Token endpoint.
  5. Confirm the new token pair works by retrying the original API call.
  6. Build a runbook around this flow so on-call engineers can recover any installation without escalating to the HighLevel API team. For unresolved cases, escalate via https://developers.gohighlevel.com/ with the traceId from the response.

Graph View

Backlinks