Resolving Salesforce “invalid_grant” Authentication Failures

 

Problem Overview

A commonly encountered error while attempting to obtain an OAuth token from Salesforce using the authorization code flow. After receiving an authorization code:

https://login.salesforce.com/services/oauth2/token

Including the following parameters:

• code

• grant_type = “authorization_code”

• redirect_uri

• client_id

• client_secret

However, Salesforce responded with:

{"error":"invalid_grant","error_description":"authentication failure"}

HTTP status code 400 accompanied the error—indicating that despite all parameters being provided, the token exchange failed unexpectedly.

Step-by-Step to Fix Authentication

The comprehensive approach to resolve this issue:

1. Create a Salesforce Developer Account
   Begin with a free developer account from developer.salesforce.com.

2. Set Up a Connected App
   From the Setup menu, navigate to Create → Apps → Connected Apps → New. Fill out required fields—including OAuth settings and callback URLs (even localhost is acceptable for testing). 

3. Configure OAuth Policies Correctly
   After registering the Connected App, edit its policies:

   • Set Permitted Users to "All users may self-authorize"

   • Set IP Relaxation to "Relax IP restrictions"

   • Add your client’s server IPs to Network Access > Trusted IP Ranges if necessary 

4. Perform the OAuth Token Request via CURL
   With these settings in place, use a CURL command to request a token. Example for production:

curl -v https://login.salesforce.com/services/oauth2/token \

  -d "grant_type=password" \

  -d "client_id=YOUR_CLIENT_ID" \

  -d "client_secret=YOUR_CLIENT_SECRET" \

  -d "username=USER_EMAIL" \

  -d "password=PASSWORD"

For sandboxes, swap the domain to https://test.salesforce.com/...

Note: Use the password flow only for development or trusted single-tenant use cases. Multi-tenant applications should use the proper OAuth code or web server flows.

Additional Insights & Common Pitfalls

Other contributors highlighted critical configuration issues that often lead to “invalid_grant” errors:

• Required Setting: “Allow OAuth Username-Password Flows”
  Ensure this option is enabled in the Connected App settings under OAuth policies. Even if IP relaxation and user authorization are configured, this requirement must be active. 

• Security Token Requirement
  If your org enforces IP restrictions and the user logging in does not come from a trusted IP, append the user's security token to their password. Reset the security token via Personal → Reset My Security Token in Salesforce. 

• Host Header Mismatch (for authorization code flow)
  If you're using the authorization code flow, ensure that your Host HTTP header matches the domain in the redirect_uri. This is especially important when a custom domain is used. A mismatch will result in the same "invalid_grant" error.

When encountering an invalid_grant / authentication failure error during Salesforce OAuth flows, use this checklist:

Step	Action
1	Create a Salesforce developer or sandbox account.
2	Register a Connected App and note the client_id and client_secret.
3	In Connected App → OAuth Policies: enable All users may self-authorize, set IP relaxation to relaxed.
4	Add trusted IP ranges if your org enforces IP restrictions.
5	If using username/password flow, append security token if needed.
6	Ensure the "Allow OAuth Username-Password Flows" setting is enabled.
7	For authorization code flow, verify that the Host header aligns with redirect_uri.
8	Test with CURL using the appropriate Salesforce endpoint (login.salesforce.com or test.salesforce.com).

Following this setup ensures that the authentication request includes all necessary permissions and environment alignment to succeed. Once working, you can tighten security settings gradually and move to more production-appropriate OAuth flows as needed.