Jonathon's AI Wiki

OAuth 2.0

3 min read

Source: ai-research/ghl-2026-05-01/docs-oauth-gettingstarted.md, ai-research/ghl-2026-05-01/docs-authorization-authorization_doc.md, ai-research/ghl-2026-05-01/support-solutions-articles-155000003717-how-to-reconnect-broken-marketplace-apps.md, ai-research/ghl-2026-05-01/support-solutions-articles-48001060529-highlevel-api-documentation.md

OAuth 2.0 is HighLevel’s authorization flow for Marketplace apps and any integration that needs to act on behalf of a user across multiple locations or companies. It is the required authentication method for any app distributed through the Developer Marketplace. The Reconnect API gives developers a way to recover lost access and refresh tokens without forcing every customer to reauthorize.

Key Takeaways

  • When OAuth is required. Use OAuth 2.0 when building a full-scale integration intended for public use, when the integration needs webhooks or custom modules, when accessing multiple locations or accounts, or when standardized authorization management and advanced security features are needed.
  • Authorization code grant flow. HighLevel uses the standard OAuth 2.0 authorization code grant. The user approves access in HighLevel, the app receives an authorization code, and that code is exchanged for an access token plus a refresh token.
  • Plan-tier requirement. Advanced API access — including OAuth and the future endpoints in HighLevel’s OAuth 2.0 API — is only available on the Agency Pro plan. Starter and Unlimited plans receive Basic API access only and use Location API keys / PITs.
  • Reconnect API for lost tokens. When access or refresh tokens are lost (HighLevel incident, developer-side error), the Reconnect API returns a fresh authorization code that can be exchanged for a new access/refresh token pair. No customer reauthorization required.
  • Two reconnect modes. Sub-account app connections call the endpoint with clientKey, clientSecret, and locationId. Agency connections use clientKey, clientSecret, and companyId.
  • Marketplace app pattern. OAuth apps are registered on the Developer Marketplace, distributed to agencies/sub-accounts, and configured to subscribe to the events they care about. See Developer Marketplace and Marketplace App Listing for the publishing flow.
  • Token endpoint. Authorization codes are exchanged via the Get Access Token API (OAuth authorization grant flow). All OAuth API calls hit https://services.leadconnectorhq.com.

Reconnect API: Sub-Account App

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

Reconnect API: Agency App

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

Reconnect Response

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

The returned authorizationCode is then passed to the Get Access Token API to obtain a fresh access/refresh token pair.

When to Use OAuth vs PIT

OAuth 2.0 is the right choice when:

  • Your integration is a public or Marketplace app.
  • You need to access multiple locations or companies from one app.
  • You require secure, user-approved access with revocable consent.
  • You need webhook subscriptions, custom workflow actions/triggers, or custom conversation providers.
  • You need standardized authorization management with refresh tokens.

For internal single-location use cases, Private Integration Tokens are the simpler choice.

Try It

  1. Sign in at marketplace.gohighlevel.com and create a new Marketplace app under the Developer Marketplace.
  2. Configure the OAuth redirect URI and the scopes your app needs.
  3. Walk a test sub-account through the install flow to confirm the authorization code → access/refresh token exchange works.
  4. Store clientKey, clientSecret, and the per-install locationId (or companyId) in your secrets store — these are exactly what the Reconnect API needs to recover.
  5. Build a token-refresh job that runs before access tokens expire, and a reconnect fallback that triggers if both tokens are lost.
  6. Subscribe to the events your app needs in Webhooks and verify delivery in the Webhook Logs Dashboard.

Graph View

Backlinks