Running into issues with your Salesforce integration? Use this guide to find quick answers to common Salesforce troubleshooting scenarios and get your Spekit integration working correctly. Some of these solutions may require Salesforce System Administrator or Spekit Account Admin-level access.
1. Common Troubleshooting for the Spekit Salesforce Integration
Most connection issues are caused by unmet requirements. Before troubleshooting further, confirm the following are all in place:
- The connecting user's Salesforce Profile has the API Enabled system permission.
- The connecting user's Salesforce Profile has the Modify Metadata Through Metadata API Functions system permission.
- IP restrictions are not blocking Spekit: either the Spekit Connected App in Salesforce is set to Relax IP restrictions, or Spekit's IP addresses are added as trusted IP ranges (see Section 6).
Check out Setting up Salesforce for more information on how to enable these settings in Salesforce.
2. "There was an error while connecting to Salesforce" When Connecting Spekit (Salesforce Metadata Integration)
When you try to connect Salesforce to Spekit from the Connect Salesforce to Spekit page, you may see the message "There was an error while connecting to Salesforce. Please try again or contact support." The page address will end in /connectSF/ip-blocked.
Despite the name in the address, this is a general connection error. In most cases the cause is that Salesforce rejected Spekit's connection request because of IP restrictions on the Spekit Connected App. Spekit's server logs show this as the Salesforce error invalid_grant - ip restricted at the point where Spekit exchanges the authorization code for an access token.
Note: The checkboxes on the Connect Salesforce to Spekit page appear unchecked after the error. This is normal. The page reloads after a failed attempt and resets, so it does not mean the earlier attempt was missing a selection.
Step 1: Confirm the Cause in Salesforce
- Log into Salesforce as a System Administrator.
- Go to Setup > Identity > Login History.
- Look for the connection attempt made at the time of the error (match the time and the user who tried to connect). Check the Status column for a failure such as Restricted IP.
- Write down the IP address shown in the Source IP column. Note that for this error, the blocked request comes from Spekit's servers, so this will be a Spekit IP address and not your own.
Step 2: Relax IP Restrictions on the Spekit Connected App (Recommended)
- Go to Setup > Apps > Connected Apps > Manage Connected Apps (or App Manager).
- Find the Spekit Connected App, and click Manage (or Edit Policies).
- Under OAuth Policies, set IP Relaxation to "Relax IP restrictions".
- Click Save.
- Try connecting Spekit to Salesforce again.
Step 3: Check Permitted Users
- On the same Spekit Connected App page, check Permitted Users under OAuth Policies.
- If it is set to "Admin approved users are pre-authorized", make sure the profile or permission set of the user connecting Spekit is assigned to the app.
- Save, then try connecting again.
Step 4: If You Cannot Relax IP Restrictions, Allow Spekit's IP Addresses
If your organization requires IP restrictions to stay enforced, add Spekit's IP addresses as trusted IP ranges. See Section 6 for the list of addresses and the steps to add them.
Step 5: Confirm the Connecting User's Permissions
The user connecting Spekit must have the permissions listed in Section 1 (API Enabled and Modify Metadata Through Metadata API Functions).
Still having issues? If the error continues after these steps, contact support@spekit.co with the date and time of your attempts (including your time zone) and the email address of the Salesforce user who tried to connect.
3. New Salesforce Data Not Syncing to Spekit
If your new Salesforce fields, objects, or users don't appear in Spekit, it's because Spekit does not automatically sync changes from Salesforce. A Spekit Administrator must perform a manual sync to pull them in.
How to Perform a Manual Sync
- Go to Settings > Connect and look for the Salesforce native integration in Spekit.
- Click Sync now.
Important: Do not navigate away from the page while the sync is processing. It might take a couple of minutes to complete. Once the sync is complete, you can define your new Salesforce field Speks.
4. OAUTH_APPROVAL_ERROR_GENERIC Error
If Spekit users get an OAUTH_APPROVAL_ERROR_GENERIC error when logging in, it typically means the Spekit OAuth application has not yet been installed in your Salesforce instance. Because of this, users are unable to self-authorize an uninstalled OAuth app.
To resolve this, a Salesforce Administrator will need to install the Spekit OAuth app in your Salesforce org. Please refer to the Setting up Salesforce article in the Spekit Help Center for step-by-step instructions.
5. 500 Error When Authenticating with Salesforce
If you get a 500 error when trying to authenticate with Salesforce for the first time, it most commonly means your organization enforces IP address restrictions at login. Follow the steps below to confirm the cause and resolve it.
Step 1: Confirm the IP Address Is the Issue
- Log into Salesforce.
- Go to Setup > Identity > Login History.
- Search the Application Name column for Spekit to find your login attempt.
- Confirm the Status column reads Restricted IP.
- Write down the IP address shown in the Source IP column. You will need this in the steps below.
Step 2: Resolution Options
Try the following solutions in order:
Option 1: Create a Trusted IP Range in Network Access
- Go to Setup > Security > Network Access.
- Click New to create a new trusted IP range.
- Enter the IP address you recorded from Login History as both the Start and End IP address.
- Click Save, then try signing into Spekit again.
Option 2: Add the IP Address to the User Profile
- If login still fails after Option 1 and the same IP address appears, go to Setup > Manage Users > Profiles and open the user's profile.
- Click Login IP Ranges, then click New and enter the IP address.
- Click Save, then try signing into Spekit again.
Option 3: Append the Security Token to Your Password
- From your Salesforce personal settings, enter Reset in the Quick Find box and select Reset Security Token.
- A new security token will be sent to the email address on your Salesforce account.
- Try logging into Spekit again by appending the security token directly to the end of your password.
Still having issues? If none of the above options resolve the error, please reach out to support@spekit.co.
6. IP Address Restriction Error When Connecting to Salesforce
To connect your Salesforce org to Spekit, your Salesforce user must have the Modify Metadata Through Metadata API Functions permission, and IP restrictions must not block Spekit.
Note: Spekit will never write to, edit, or access your customer data.
Step 1: Relax IP Restrictions on the Spekit Connected App, or Add Spekit's IP Addresses
The simplest fix is to set IP Relaxation on the Spekit Connected App to "Relax IP restrictions" (see Section 2). If your organization must keep IP restrictions enforced, add the following IP addresses to your Salesforce trusted IP ranges. Spekit uses Port 443.
- 3.139.185.210
- 3.18.141.125
- 3.19.233.113
- 3.124.215.118
To add these IP ranges in Salesforce:
- Click Setup in Salesforce.
- In the Quick Search on the left side of the page, search for Network Access and click it.
- Click New.
- Enter the Start IP Address and End IP Address for the range.
- Enter Spekit in the Description field.
- Click Save. Repeat for each IP address to be added.
Note: IP ranges in Salesforce can only be added or removed by a System Administrator.
Step 2: Append the Security Token to Your Password
- Open your Salesforce personal Settings.
- Enter Reset in the Quick Find box and click Reset Security Token.
- A new security token will be sent to the email address on your Salesforce account.
- Try logging into Spekit again by appending the security token directly to the end of your password.
Step 3: Check Connected Apps OAuth Usage
If the issue persists and is not related to IP addresses, check your Connected Apps OAuth Usage settings:
- Open Salesforce and click the gear icon, then select Setup.
- In the search box, enter OAuth and select Connected Apps OAuth Usage.
- Locate the Spekit line item in the list.
- Click the Install button and select Allow profiles to connect to the new Connected App for Spekit.
Still having issues? If none of these steps resolve the problem, please reach out to support@spekit.co.
7. How to Create CSP Trusted Sites to Access Third-Party APIs
Customers with IP restrictions can connect Spekit to Salesforce by adding Spekit as a Content Security Policy (CSP) Trusted Site. This approach helps prevent cross-site scripting (XSS) and other code injection attacks while allowing Spekit to make requests to Salesforce.
To set this up, follow Salesforce's official guide on creating CSP Trusted Sites to access third-party APIs.
When defining the CSP Trusted Site, add Spekit's URL to the list of allowed sites. This permits Spekit to make external API requests and use WebSocket connections without being blocked by Salesforce's CSP header.
[Needs review — specify which Spekit URL(s) to add as the Trusted Site and which CSP directives to enable.]
8. "Could Not Complete Sync" Error
This error appears when you go to the Connect page and click Sync Now, and a red error message appears in the bottom-left corner of the screen. It indicates that something has changed with the Salesforce connection since it was originally set up.
Below are the most common causes and how to resolve each one:
- The Salesforce user used to connect Spekit is no longer active. Go to the Connect page and check the name listed next to Connected by. Contact your Salesforce Administrator to confirm that user has not been deactivated.
- The Salesforce user does not have the required permissions to sync. Update the Salesforce User Profile to meet the required permissions outlined in Section 1.
- The Salesforce OAuth token is no longer valid or needs to be reset. Contact support@spekit.co and the Spekit Support team will assist you in resetting the token.
9. How to Find the URL of an iFrame or Visualforce Page
Some pages, such as Visualforce pages, use iFrames to display content. Because an iFrame runs on a different URL from the main page, Spek icons will not appear inside it unless you add the iFrame's URL to the relevant Topic.
- Right-click anywhere inside the Visualforce page or iFrame.
- Click View Frame Source from the context menu.
- A new tab will open and the Chrome address bar will display a URL beginning with
view-source:followed by the iFrame URL, for example:view-source:https://yourorg.visual.force.com. - Everything after
view-source:is the URL you need. Copy this URL (leaving out theview-source:prefix) and add it to the Topic in Spekit where you want Spek icons to appear.
10. How to Enable Spek Icons on the Edit Quote Screen in CPQ
The Edit Quote screen in Salesforce CPQ uses a Visualforce page, which requires a few additional steps to enable Spek icons.
- Open the Salesforce CPQ app and navigate to the CPQ Quote object (
SBQQ__Quote__c). - Click to open a Quote record (for example, Q-00000).
- Click Edit Lines.
- Follow the steps in Section 9 to get the correct Visualforce URL for this page. It will contain
sbqq, the prefix for the CPQ managed package. - Create a new or edit an existing Topic in Spekit and add the URLs for the Salesforce
one.appand the Salesforce CPQ prefix (for example,https://sbqq.[yourorg].visual.force.com). - Open a new browser tab, paste the copied URL into the address bar, and press Enter. The Edit Quote Visualforce page will load on its own.