Salesforce Dictionary - Free Salesforce GlossarySalesforce Dictionary
All errors
Security

invalid_grant: invalid_grant - challenge required / TWO_FACTOR_REQUIRED

Salesforce required Multi-Factor Authentication for the login but the integration didn't supply it. Most common with Username-Password OAuth flow against a profile that requires MFA. The fix is to switch the integration to JWT bearer flow (which is MFA-exempt) or to give the integration user the "API Only User" permission set.

Also seen asTWO_FACTOR_REQUIRED·challenge required·MFA required·Multi-Factor Authentication

Salesforce mandated MFA for production logins starting February 2022. Org-wide enforcement combined with the "Multi-Factor Authentication for User Interface Logins" session security policy means human users see an MFA challenge on every login.

The complication: integrations using the legacy Username-Password OAuth flow can't pass an MFA challenge programmatically. They get this error.

The five paths forward

Path 1: switch to JWT bearer flow (recommended)

JWT flow doesn't go through interactive login at all. The integration server signs a JWT with a private key; Salesforce validates against the public cert in the connected app. No password, no MFA.

sf org login jwt \
  --client-id YOUR_CONNECTED_APP_CONSUMER_KEY \
  --jwt-key-file server.key \
  --username integration@example.com \
  --instance-url https://yourdomain.my.salesforce.com

Setup steps:

  1. Generate a key pair: openssl req -x509 -newkey rsa:2048 -keyout server.key -out server.crt -days 730 -nodes
  2. Create a Connected App in Salesforce; under Use digital signatures, upload server.crt
  3. Pre-authorize the integration user via Connected App Policies → Permitted Users → Admin approved users

Path 2: API Only User permission set

Setup → Permission Sets → Salesforce API Only System Integrations (or the modern "API Only User" permission set). Assign to the integration user. They can no longer log into the UI but they're exempt from MFA on the API.

Path 3: High-Assurance Session

If the integration must use Username-Password and you can't switch flows, the integration user's profile can have High Assurance Session = Allow for the connected app. Then a one-time MFA registration is sufficient; subsequent logins skip the challenge. This is fragile but sometimes the only available path.

Path 4: SAML-bonded integrations

Some enterprise IDPs let you whitelist specific service accounts with no MFA. This is configured in your IDP, not in Salesforce.

Path 5: Stop using Username-Password OAuth

Salesforce is sunsetting the Username-Password OAuth flow. The Spring '24 release deprecated it for new orgs; it'll be removed entirely on a future release. Plan migration sooner rather than later.

When MFA is required for ALL logins

Salesforce's Spring '22 release also enforces MFA for Web logins, including OAuth flows where the user enters credentials in a browser. If your integration redirects users to log in (Web Server flow), they'll see the MFA challenge themselves. That's expected; the user provides MFA, the OAuth callback completes, your integration gets a token.

This is fine for human-facing OAuth integrations. The TWO_FACTOR_REQUIRED error specifically refers to programmatic logins where no human is present to answer the challenge.

Diagnose with the OAuth response

The OAuth error response includes details:

{
  "error": "invalid_grant",
  "error_description": "MFA challenge required for this user. ..."
}

That error_description is what tells you it's MFA, not just a wrong password.

Related dictionary terms