Troubleshooting Salesforce Connection Issues

Connecting or Updating the Salesforce Connection

To connect or update your Salesforce connection within the HG Insights platform, navigate to the Integrations section from the left-hand sidebar of the HG Admin App: https://admin.hginsights.com/. Once there, click on Salesforce to access the integration page.

Here, you will find options to initiate a new connection or update an existing one. If you are updating, ensure you log out of any active Salesforce accounts to avoid connection issues. Follow the prompts to complete the OAuth authorization process, and you will be set to enhance your CRM capabilities with HG Insights data.

Connection requirements

Confirm your integration user is correct

The integration user is the Salesforce user who authorizes the connection. HGI’s RGI Platform syncs data using this user's permissions, so a dedicated integration user is recommended (the connection won't break if an employee leaves).

Verify user permissions

Ensure that the login credentials for both HG Insights and Salesforce are correct and have the necessary permissions for integration:

You should be an HG Insights platform admin user to be able to edit the Salesforce connection. Check it under Settings/Users & Teams
We recommend being a Salesforce Admin in the org you’re trying to connect to HG Insights, although we provide workaround steps here. Recent Salesforce security changes (effective September 2025) require connected apps to be installed and approved by an admin before non-admin users can authorize them. This is why the steps below depend on your setup.

Once this is sorted, please try to connect again.

Update your SFDC package to the latest version

HG Insights regularly releases new package versions. We have 2 packages depending on your usecase. You can find the latest ones below:

Troubleshooting specific errors

We can't authorize you because of an OAuth error. error=invalid_client&error_description=app+must+be+installed+into+org

Cause: the connected app exists in the org but has never been installed, so Salesforce blocks every login attempt against it. Since Sept 2025 — Salesforce blocks OAuth for any connected app that isn't installed unless the user holds “Approve Uninstalled Connected Apps.”

Fix: Install the app into your org first, then try to connect again. After installing, also confirm Permitted Users and relax any IP restrictions on the connected app, then verify the stored credential includes a refresh token

Cause: the connecting user has the API Only User permission enabled, which blocks browser-based OAuth.

Fix: Uncheck it on that user's profile/permission set

There are additional steps you can go through to make sure your API-only user can connect: API-only SFDC users - Troubleshooting Salesforce connection issues

If you still cannot connect using an API-only user, please do get in touch at customersupport@hginsights.com. As an immediate workaround, you can first connect SFDC using an admin user, then immediately update the connection to use the API)only user.

Cause: Your Salesforce org is likely blocking HG Insights' servers from renewing the connection in the background (a refresh-token IP restriction). See Salesforce C onnection Security Requirements for why this control exists.

Fix: Ask your Salesforce admin to relax the IP restriction on the connected app:

In Salesforce, go to Setup → Apps → App Manager → Manage Connected Apps (or Connected Apps OAuth Usage, depending on your org).
Find the HG Insights connected app and open Edit Policies.
Set IP Relaxation to "Relax IP restrictions".

If IP Relaxation is already set to "Relax IP restrictions" and the problem persists, please contact Support.

"PKCE verifier expired. Please reconnect Salesforce" on the OAuth screen

Fix: Refresh the page and restart the OAuth flow, completing it promptly. This is a time-limited security check — see Salesforce Connection Security Requirements for details.

Need Assistance?

Reach out to Support at customersupport@hginsights.com or via our shared Slack channel if you have Slack support activated.

Kindly include screenshots or screen recordings that illustrate where the process encounters issues for you. Providing specific error messages and URLs from the error page will assist us in resolving your problem quickly and can help prevent unnecessary exchanges.