How to fix Salesforce OAuth error OAUTH_APPROVAL_ ERROR_GENERIC

This article explains why the Salesforce OAUTH_APPROVAL_ERROR_GENERIC issue occurs, how to diagnose it, and the specific steps required to resolve it.

The Salesforce OAUTH_APPROVAL_ERROR_GENERIC typically occurs during the initial authorization step. It blocks the OAuth authorization flow, preventing users from connecting third-party applications to their Salesforce instance. There can be many causes; this article explains how to diagnose and fix it.

Add image fix-salesforce-oauth-error-oauth_approval_error_generic.png here

Understanding the Salesforce error: OAUTH_APPROVAL_ERROR_GENERIC

Salesforce uses Connected Apps to manage OAuth applications. A Connected App is the equivalent of a Slack app or a GitHub OAuth app. However, the installation of Connected Apps on a Salesforce Instance can be controlled by the Salesforce Admin. Admins decide if users can install apps, how long access tokens remain valid, and which IP addresses can access the API.

When a user attempts to install or authorize a Connected App, the Salesforce instance's security restrictions evaluate the request. If the policies prohibit the installation, Salesforce halts the flow before the approval dialog even renders. Because the UI is entirely blocked, Salesforce throws a generic error rather than a specific access denial. (Generic OAuth errors are a common pain point across APIs.)

Add image salesforce_OAUTH_APPROVAL_ERROR_GENERIC.png here

Diagnosing the issue: check the URL

Because the error message on the screen is generic, the fastest way to pinpoint the exact root cause is to inspect the URL in the browser when the error occurs.

Salesforce appends specific parameters to the URL that describe the failure. Look for the error and error_description parameters.

Here is an example of what the callback URL might look like:

https://example.com?
error=invalid_client&
error_description=app+must+be+installed+into+org

This specific description is the most common trigger for the Salesforce oauth_approval_error_generic error for Connected Apps.

Root causes and solutions for OAUTH_APPROVAL_ERROR_GENERIC

Below are the known root causes for the OAUTH_APPROVAL_ERROR_GENERIC error and their high-level resolutions.

1. Connected App Usage restrictions (most common)

Salesforce recently updated its security posture. By default, users cannot freely authorize third-party apps unless an Admin has explicitly trusted them. If the Connected App is not installed in the org, Salesforce checks if the user has the "Approve Uninstalled Connected Apps" permission. If they lack this permission, the flow fails.

The solution:

You have two ways to resolve this:

• Org-Level App installation (recommended): A Salesforce Admin must navigate to the Connected Apps OAuth Usage settings and manually install the specific app.

Add image salesforce_connected_apps_oauth_usage.png here

They can then set the "Permitted Users" policy to either allow all users to self-authorize or restrict it to Admin-approved users.

Add image salesforce_connected_apps_oauth_installation_permissions.png here

• User-level permission: An Admin can grant specific power users the ability to authorize any app. This requires enabling the "Approve Uninstalled Connected Apps" system permission within a user's profile or through a dedicated Permission Set.

Add image ApproveUninstalledConnectedApps.png here

Tip: See the official Salesforce notification regarding the change to Connected App usage restrictions.

2. Missing or incorrect OAuth scopes

The OAuth authorization request must specify the required "scopes" (permissions). If the request asks for scopes that the Connected App is not configured to allow, the flow will fail.

The solution:

Ensure the scopes requested in your authorization URL exactly match the "Selected OAuth Scopes" configured in the Salesforce Developer Edition instance. Common required scopes include api, refresh_token, and offline_access. Do not request a blanket full scope in the URL if the app is only configured for granular scopes.

Add image salesforce_oAuth_scopes.png here

// for debugging, you can get scopes assigned to a token from the below endpoint
curl -H 'Authorization: Bearer $ORG_ADMIN_TOKEN' \
'https://anypoint.mulesoft.com/accounts/api/
connectedApplications//scopes?offset=0&limit=100'
  

Tip: See how to get the scopes assigned for a Connected App

3. IP Address restrictions

If a Connected App or a user's Profile has strict Login IP Ranges configured, requests originating outside those ranges will fail. Even though this is technically a login restriction, the Connected App flow masks it as a generic approval error.

The Solution:

• Verify the Login IP Ranges on the user's Profile. Ensure that the IP address of the third-party service (or the user's current network) is explicitly whitelisted.
• Alternatively, an Admin can relax IP restrictions on the Connected App's policies by going to "Setup > Connected Apps > APP > Edit Policies" and setting "IP Relaxation" to Relax IP restrictions.

Add image salesforce_relax_ip_restrictions.png here

4. Sandbox refresh and licensing issues (rare)

If you see this error immediately after a Sandbox refresh, the refresh likely wiped your installed Connected Apps. Furthermore, the Sandbox may have lost the specific license configurations required to even display the "Approve Uninstalled Connected Apps" permission in the settings.

The solution:

Navigate to the Company Information settings in the Sandbox and run the "Match Production Licenses" tool. This resyncs the license definitions, restoring the missing permissions so you can properly authorize the app.

Add image match_production_licenses.png here

5. Enforced PKCE Requirements

Recent Salesforce updates (the Spring '26 security enforcement) mandate the use of Proof Key for Code Exchange (PKCE) for secure OAuth flows. If you are using legacy tools or older custom apps that do not send a PKCE challenge during the handshake, the Org will reject the request.

The Solution:

Update your integration to support PKCE. If you are relying on an outdated legacy app, an Admin can temporarily disable PKCE enforcement in the Org's OAuth and OpenID Connect Settings.

Add image Salesforce_disable_pkce.png here

Summary of error triggers for OAUTH_APPROVAL_ERROR_GENERIC

Note: If you have resolved the underlying configuration issue and the error persists, instruct the user to clear their browser cache and cookies before retrying.

Related Salesforce OAuth errors

• invalid_grant: Often related to expired or revoked refresh tokens.
• invalid_client: Usually indicates an incorrect Client ID or Client Secret.
• redirect_uri_mismatch: The callback URL in the request does not exactly match the one configured in the Connected App.

Using Nango for Salesforce integrations

Integrating external APIs and debugging their OAuth errors across hundreds of customer Salesforce orgs is a massive time sink, and Salesforce OAuth has other quirks, such as not including an access token's expiration time in the token response. Managing OAuth at scale also involves refresh token (invalid_grant) and concurrency issues during token refresh.

Nango handles these things for you. Nango is an open-source, developer-first platform that simplifies the management of API integrations for over 700 APIs. Instead of writing boilerplate code for every OAuth flow, you can use Nango's pre-built primitives to handle the entire lifecycle of your Salesforce connection.

import { Nango } from '@nangohq/node';
const nango = new Nango({ secretKey: '' });
const res = await nango.get({
    endpoint: '/services/data/v58.0/query',
    params: { q: "SELECT Id, FirstName, LastName, Email FROM Contact LIMIT 10" },
    providerConfigKey: '',
    connectionId: ''
});
console.log(res.data);
  

Add image NangoSalesforceIntegration.png here

Nango also has detailed real-time logging and error alerts for webhook payloads and all API interactions.

Add image Nango_logs.png here

To get started, check out the Nango Salesforce documentation and follow our Auth implementation guide to integrate Nango in your app. For a step-by-step build, see how we built a Salesforce API integration in 3 hours.