How to fix Salesforce OAuth error OAUTH_APPROVAL _ERROR_GENERIC

Why the OAUTH_APPROVAL_ERROR_GENERIC issue occurs for Salesforce API integrations, how to diagnose it, and the specific steps required to resolve it.

Table of contents

Example H2

When building Salesforce API integrations, the OAUTH_APPROVAL_ERROR_GENERIC error 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 are many reasons this error can occur; this article explains how to diagnose and fix it.

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.)

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 updated its security posture in September 2025. 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.

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

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.

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.

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:‍

A Salesforce Admin can verify the Login IP Ranges on the user's Profile. The Admin should 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.

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.

5. Enforced PKCE requirements

Salesforce Spring ’26 release (which rolled out to production between January 16 and February 20, 2026) mandates 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.

Tip: If you're using Nango, it automatically adds PKCE for Salesforce API integrations.

Summary of error triggers for `OAUTH_APPROVAL_ERROR_GENERIC`

Root Cause	Context	Fix
App Not Installed	Security blocks uninstalled apps.	Admin installs the app or grants the user permission to approve uninstalled apps.
Scope Mismatch	URL scopes differ from App scopes.	App developer aligns the requested URL scopes with the configured App scopes.
Sandbox Refresh	Sandbox loses license state.	Admin runs the "Match Production Licenses" tool in the Sandbox.
IP Restriction	Request originates from an untrusted IP.	Whitelist the IP address in the User Profile or relax Connected App IP policies.
Missing PKCE	Org requires PKCE, app omits it.	Implement PKCE in the OAuth flow or disable the Org requirement.

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 600 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 integration.

import Nango from '@nangohq/frontend';
const nango = new Nango();
// Open Nango UI that walks the user through connecting the API
const connect = nango.openConnectUI({
  onEvent: (event) => {
    if (event.type === 'close') {
        // Handle modal closed.
    } else if (event.type === 'connect') {
        // Handle auth flow successful.
    }
  },
});
// Set config for this auth flow (loaded from Nango API)
connect.setSessionToken(this.sessionToken);