Setting Up OAuth2 Authentication with Salesforce

How the connection works and why it matters

The Salesforce app uses OAuth2 with the Authorization Code grant. Your Client ID and Client Secret identify the app, but Salesforce always requires a real user to log in and authorize access before it issues a token.

Here's what happens when you connect:

Step	What happens	Reference
1	You click Connect. Pipefy redirects you to the Salesforce login page.	`authUrl`
2	You log in and authorize the app on the page hosted by Salesforce.	login + consent
3	Salesforce redirects back with a one-time-use `code` to the callback URL.	`redirect_url`
4	Pipefy exchanges the `code` for a token, using your Client ID + Secret.	`grant_type=authorization_code`

After that, token renewals happen automatically using grant_type=refresh_token and don't require you to log in again, which is why the refresh_token scope is required on the connection.

To connect SalesForce at Pipefy Integrations, should be used the method OAuth2app (Advanced), clicking on Try another method, when open the connection setup.

What you need before connecting

Both sides of the connection, the Connected App in Salesforce and the connection in Pipefy, need to be set up correctly:

A Connected App created in Salesforce with OAuth enabled and Enable Authorization Code and Credentials Flow checked.
The Connected App's Callback URL matches exactly what Pipefy uses (e.g., https://ipaas.pipefy.com/redirect), no trailing slash mismatch, no http instead of https.
OAuth Scopes include, at minimum, api, refresh_token/offline_access, and full.
Client ID and Client Secret copied from the Connected App into the Pipefy connection field.
The Salesforce Domain field filled in with login.salesforce.com, test.salesforce.com, or your My Domain (yourcompany.my.salesforce.com), never a lightning.force.com domain.
The user who will authorize the connection has the API Enabled permission on their Profile/Permission Set.

Salesforce Setup — Connected App → OAuth Policies (simplified reference)

Callback URL: https://ipaas.pipefy.com/redirect  Selected OAuth Scopes: api · refresh_token, offline_access · full  Enable Authorization Code and Credentials Flow: [ON]

🛠️ Troubleshooting: Common configuration errors

Each item below shows the symptom, the most likely cause, and the fix.

1. UI domain used instead of the API domain — 🔴 blocks the connection

Error: INVALID_CLAIM — "grant type not supported" Cause: The Salesforce Domain field was filled in with the Lightning Experience domain (e.g., yourcompany.lightning.force.com), which is not Salesforce's authentication/API host. Fix: Replace it with your API My Domain (yourcompany.my.salesforce.com) or login.salesforce.com/test.salesforce.com, available under Setup → My Domain.

2. Callback URL mismatch — 🔴 blocks the connection

Error: redirect_uri_mismatch / invalid redirect_uri Cause: The Callback URL registered on the Connected App differs, character for character, from the one Pipefy uses — including protocol and trailing slash. Fix: Copy the exact value shown on the Pipefy connection screen and paste it into the Connected App's Callback URL field.

3. OAuth flow disabled in the app's policies — 🟡 context-dependent

Error: unsupported_grant_type Cause: The Enable Authorization Code and Credentials Flow option is unchecked in the Connected App's OAuth Policies — even with the correct domain and Callback URL, the grant is refused. Fix: Edit the Connected App under Setup → App Manager, check the option, and save.

4. Connected App recently created or edited — 🟡 context-dependent

Error: invalid_client_id (temporary) Cause: Changes to a Connected App can take a few minutes to propagate in Salesforce. Fix: Wait about 10 minutes after creating or editing the app before trying to connect again.

5. Client Secret rotated — 🔴 blocks the connection

Error: invalid_client_id / invalid_client Cause: Someone generated a new Consumer Secret in Salesforce (manual rotation or a security policy), invalidating the value saved in the Pipefy connection. Fix: Copy the new Client Secret and update the existing connection in Pipefy.

6. IP restriction on the Connected App or Profile — 🟡 context-dependent

Error: invalid_grant — ip restricted Cause: The Connected App's IP Relaxation policy is set to Enforce IP restrictions, and Pipefy's outbound IP is not on the user's Profile allowlist. Fix: Set IP Relaxation to Relax IP restrictions on the Connected App, or add Pipefy's IPs to the Login IP Ranges on the user's Profile.

7. Sandbox and production mixed up — 🟡 context-dependent

Error: authentication failure / invalid_grant Cause: The Salesforce Domain field points to login.salesforce.com (production) while the Connected App and user only exist in the sandbox, or vice versa. Fix: Confirm which org the Connected App was created in and use the matching domain: test.salesforce.com for sandbox.

8. User without API access — 🟡 context-dependent

Error: API_DISABLED / insufficient_scope Cause: The Profile or Permission Set of the user authorizing the connection doesn't have the API Enabled permission — common on more restricted licenses (e.g., some platform profiles). Fix: Enable API Enabled on the user's Profile/Permission Set under Setup → Profiles, or use a dedicated integration user with that permission.