Use this guide when your Salesforce integration fails to connect, disconnects on its own, or returns an error during authentication. Most connection problems come from the permissions or access settings on the Salesforce user that authorizes the integration.
For first-time setup and the full permissions list, see The Salesforce Integration and Salesforce Integration Permissions.
Common Connection Errors
| Error or symptom | Likely cause | How to fix it |
|---|---|---|
| "Failed to fetch organization data" | The integration user is missing one or more required System Permissions. | Grant the user API Enabled, View Setup and Configuration, and View All Data, then reconnect. |
| "User is not approved to access this app," or a generic OAuth error | The Salesforce Connected App allows pre-authorized users only, and the integration user is not included. | Ask a Salesforce admin to update the Connected App so the integration user is permitted. See Approve the Connected App. |
| Sign-in succeeds, but you return to the Oktopost dashboard with an error | The user authenticated but could not complete the handshake, often due to permissions, a multi-factor prompt, or a session restriction. | Confirm the user's permissions, complete any multi-factor authentication challenge, and check for IP or session restrictions in Salesforce. |
| "Invalid credentials," or the integration shows as disconnected | The integration user's password changed, the user was deactivated, or their access was revoked. | Reconnect while signed in as an active user. See Reconnect the Integration. |
Approve the Connected App
When Salesforce restricts a Connected App to pre-authorized users, a Salesforce admin must grant the integration user access.
- Sign in to Salesforce as an administrator.
- From Setup, use Quick Find to open Manage Connected Apps.
- Open the relevant app and click Edit.
- Under OAuth Policies, adjust Permitted Users, or assign the profile or permission set used by the integration user.
- Save, then reconnect the integration in Oktopost.
Reconnect the Integration
- Sign in to Salesforce in a separate browser tab as the same user that originally connected the integration.
- In Oktopost, go to Settings > General > Integrations.
- Click the Salesforce integration, then click Reconnect.
Find or Change the Integration User
The integration user is the Salesforce user whose access authorizes the connection. If that user is deactivated or leaves the company, the integration stops working. If you are not sure which user is connected, reach out to your account manager.
To move the connection to a different Salesforce user:
- Take a screenshot of your current Salesforce integration settings so you can re-apply them.
- In Oktopost, go to Settings > General > Integrations and remove the Salesforce integration.
- Sign in to Salesforce as the user you want to use as the new integration user.
- Add the Salesforce integration again and complete authentication as that user.
Allowlist Oktopost's IP Address
If your Salesforce org restricts API access by IP address, add Oktopost's integration IP address to your allowlist so the connection and sync can complete. Reach out to your account manager for the current IP address to allowlist.
Still Need Help
If the connection still fails after these steps, note the exact error message and the date and time in UTC of your last attempt, then reach out to your account manager.
Frequently Asked Questions
Why did my integration disconnect on its own?
The most common cause is a change to the integration user in Salesforce, such as a password reset, a deactivated account, or revoked permissions. Reconnect while signed in as an active user with the required permissions.
Do I need a Salesforce admin to connect the integration?
The user that authorizes the connection needs Admin access in both Oktopost and Salesforce, along with the permissions listed in the Salesforce Integration Permissions article. If your Connected App is restricted to pre-authorized users, a Salesforce admin also needs to approve the integration user.