Overview
Soapbox Engage connects to Salesforce to create, retrieve, and update records, including donations, contacts, campaigns, event registrations, and other information.
For security, we recommend connecting Soapbox Engage using a dedicated Salesforce Integration User rather than a Salesforce account belonging to an employee or administrator.
Salesforce provides a Salesforce Integration user license designed for API-based connections. Supported Salesforce organizations include a limited number of these licenses, allowing organizations to connect applications such as Soapbox Engage without necessarily purchasing an additional full Salesforce user license.
Using a dedicated Integration User offers several benefits:
- Improved security: Grant access only to the Salesforce information Soapbox Engage needs.
- Better auditing: Easily identify changes made by Soapbox Engage in Salesforce.
- Greater reliability: Avoid integration interruptions when an employee leaves or changes their Salesforce credentials.
- Stronger access controls: Restrict the connection to approved IP addresses and, for OAuth integrations, explicitly authorized Connected Apps.
This guide walks you through creating, configuring, and securing a Salesforce Integration User for Soapbox Engage.
Before you begin
You'll need:
- Salesforce System Administrator access.
- An available Salesforce Integration user license.
- Administrator access to your organization's Soapbox Engage account.
- An email address controlled by your organization for the Integration User.
- Knowledge of which Soapbox Engage applications your organization uses.
Step 1: Identify your Salesforce integration type
Soapbox Engage supports two Salesforce authentication methods.
| Integration method | Applies to | Authentication |
|---|---|---|
| Traditional Salesforce integration | Soapbox Engage connections using username, password, and security token | Salesforce API credentials |
| OAuth integration | Salesforce Nonprofit Cloud (NPC), including the Fundraising Business API, and other OAuth-enabled connections | Salesforce authorization through the Soapbox Engage Connected App |
If your organization uses the Salesforce Nonprofit Cloud specifically with the Soapbox Engage Donations app, follow the OAuth integration instructions. If you additionally use other Soapbox Engage apps, follow the Traditional Salesforce integration instructions as well to ensure their successful integration.
Both methods share the initial user, profile, and permission-set setup steps.
Part 1: Create your dedicated Salesforce Integration User
These steps apply to both traditional and OAuth integrations.
Step 2: Create an Integration User profile
We recommend creating a dedicated profile for Soapbox Engage. This allows your organization to manage login IP restrictions and applicable record type settings independently of other Salesforce users.
- In Salesforce, click the gear icon and select Setup.
- In the Quick Find search box, enter Profiles.
- Select Profiles.
- Find the Salesforce-provided profile named Minimum Access - API Only Integrations.
- In some Salesforce organizations, you may not find it. In these cases, use the profile may be named Salesforce API Only System Integrations.
- Click Clone.
- Enter the following information:
| Field | Value |
|---|---|
| Profile Name | Soapbox Engage Integration User |
| User License | Salesforce Integration |
- Click Save.
Confirm API access
Open the newly created profile and verify the following Administrative Permissions:
- API Enabled: Enabled
- API Only User: Enabled
These permissions are ordinarily provided by Salesforce's API-only integration profile. You don't need to enable them again in the Soapbox Engage permission set if the profile already provides them.
Step 3: Create the Integration User
- In Salesforce Setup, search for Users.
- Select Users.
- Click New User.
- Complete the fields using the recommended naming convention:
| Field | Recommended value |
|---|---|
| First Name | Soapbox Engage |
| Last Name | Integration |
| Alias | sbxint |
| (an IT-managed email address controlled by your organization) | |
| Username | (a unique username following your organization's naming conventions) |
| Nickname | sbxint |
| User License | Salesforce Integration |
| Profile | Soapbox Engage Integration User |
Username: Salesforce requires usernames to be globally unique across Salesforce organizations. We recommend using a descriptive, organization-specific username that follows your existing account naming conventions.
Email: Use an organizational email address rather than an individual employee's email address, so important Salesforce notifications aren't dependent on one person.
- Verify that the user is marked Active.
- Enable the Marketing User checkbox.
- Click Save.
Marketing User: Soapbox Engage uses Salesforce Campaigns, including creating Campaign records in supported workflows. We recommend enabling Marketing User for all Soapbox Engage Integration Users.
If Salesforce doesn't allow you to enable this checkbox for the Integration User, see Troubleshooting Marketing User Checkbox for Integration User.
You now have created a dedicated Salesforce user for Soapbox Engage.
Step 4: Assign the Salesforce API Integration permission set license
The Salesforce Integration user license provides API-only functionality. The separate Salesforce API Integration permission set license makes additional Salesforce object and system permissions available to the user.
- In Salesforce Setup, navigate to Users → Users.
- Select your new Soapbox Engage Integration user.
- Find Permission Set License Assignments.
- Click Edit Assignments.
- Select Salesforce API Integration.
- Add it to the enabled licenses.
- Click Save.
Important: This license assignment doesn't automatically grant access to every Salesforce object. You'll configure those permissions in the next section.
Part 2: Create the Soapbox Engage permission set
Step 5: Create a permission set
Permission sets allow you to grant access to specific Salesforce objects, fields, and applications without giving the Integration User broad administrative privileges.
- In Salesforce Setup, search for Permission Sets.
- Select Permission Sets.
- Click New.
- Enter:
| Field | Value |
|---|---|
| Label | Soapbox Engage API Access |
| API Name | Soapbox_Engage_API_Access |
| Description | Grants access to the Salesforce objects, fields, and Connected App required by Soapbox Engage. |
| License | --None-- |
- Click Save.
We recommend selecting None for the permission set license. This allows you to configure Connected App access within the same permission set.
Why not give Soapbox Engage administrator permissions?
Soapbox Engage needs access to the records used by your integration, not unrestricted administrative control over Salesforce.
Avoid granting these permissions unless specifically required:
- Modify All Data
- View All Data
- Customize Application
- Manage Users
- Modify All Records
- Delete permissions
Step 6: Configure object and field permissions
In your Soapbox Engage API Access permission set, you will need to configure a number of object settings. Below is the process you'll go through for each object listed in this step:
- Select Object Settings.
- Select the Salesforce object you want Soapbox Engage to access.
- Click Edit.
- Under Object Permissions, enable:
- Read
- Create
- Edit
- Under Field Permissions, enable Read Access and Edit Access for the fields Soapbox Engage uses, including applicable custom fields.
- Click Save.
- Repeat these steps for the applicable objects below.
Important: Only configure objects used by your Soapbox Engage applications. You do not need to give Soapbox Engage access to unrelated objects. Avoid enabling Delete, View All Records, or Modify All Records unless specifically required.
Step 6A: If your organization uses Salesforce Nonprofit Success Pack (NPSP)
For organizations using NPSP, configure Read, Create, and Edit access for the following objects, where present and applicable.
Core Salesforce and NPSP objects
- Account
- Address
- Affiliation
- Campaign
- Campaign Member
- Contact
- GAU Allocation
- General Accounting Unit
- Lead
- Opportunity
- Payment
- Recurring Donation
If using Soapbox Engage Events app or Classes app
- Attendance
- Ticket
- Ticket Temp
If using Soapbox Engage Shop app
- OLI Temps
- Price Book
- Price Book Entry
- Product
Some objects are provided by NPSP or other installed Salesforce packages and may have slightly different names in your organization. If an object doesn't exist in your Salesforce organization, skip it.
Step 6B: If your organization uses Salesforce Nonprofit Cloud (NPC)
For organizations using NPC, the fundraising data model differs from NPSP.
Configure Read, Create, and Edit access for these common Salesforce objects, where applicable:
- Account
- Campaign
- Campaign Member
- Contact
- Lead
If using Soapbox Engage Events app or Classes app
- Attendance
- Ticket
- Ticket Temp
If using Soapbox Engage Shop app
- OLI Temps
- Price Book
- Price Book Entry
- Product
For NPC Fundraising objects such as Gift Transactions, Gift Commitments, and Gift Designations, use Salesforce's standard Fundraising Access permission set, which you'll configure in Part 3. You don't need to recreate all those Fundraising permissions manually in your Soapbox Engage permission set.
Custom Salesforce fields and objects
Many organizations use custom Salesforce fields or objects with Soapbox Engage.
You can grant access to these directly through the same Soapbox Engage API Access permission set.
For custom fields:
- Open the relevant object under Object Settings.
- Click Edit.
- Find the custom field under Field Permissions.
- Enable Read Access and, where Soapbox Engage writes to the field, Edit Access.
- Click Save.
For custom objects, select the object and enable Read, Create, and Edit as required by your Soapbox Engage configuration. There's no need to create a separate permission set solely for custom fields or objects unless your organization prefers that approach.
Record-level access: Object and field permissions don't automatically grant visibility into every individual record. If Soapbox Engage cannot find or update records, review Salesforce sharing settings before granting broader access.
Step 7: Assign the Soapbox Engage permission set
- Navigate to Setup → Users → Users.
- Open Soapbox Engage Integration.
- Find Permission Set Assignments.
- Click Edit Assignments.
- Add Soapbox Engage API Access.
- Click Save.
Part 3: Additional setup for Salesforce Nonprofit Cloud
Complete this section if your organization uses Salesforce Nonprofit Cloud (NPC) Fundraising with the Soapbox Engage Donations app.
Salesforce provides a standard permission set specifically intended for third-party donation platforms using its Nonprofit Cloud (NPC) fundraising functionality.
Step 8: Assign Fundraising Access
- In Salesforce Setup, search for Users.
- Open Soapbox Engage Integration.
- Find Permission Set License Assignments.
- Verify that Fundraising Access is assigned. If it isn't, add it and save.
- Find Permission Set Assignments.
- Click Edit Assignments.
- Add the Salesforce-provided Fundraising Access permission set.
- Click Save.
The Fundraising Access permission set provides Salesforce-managed fundraising permissions and entitlements, including the applicable Fundraising User system permission.
You do not need to duplicate every Fundraising object and field permission in your custom Soapbox Engage permission set.
Important: Do not assign the broader Fundraising_Admin or Fundraising_User permission set groups solely for this integration. These may include license requirements incompatible with Salesforce Integration Users.
Step 9: Configure Person Account record types
Nearly every Nonprofit Cloud organization uses Person Accounts, so in these cases you must ensure the Integration User can use the appropriate Person Account record type. Missing or incorrect record type assignments can cause Fundraising Business API requests to fail.
- In Salesforce Setup, search for Profiles.
- Open Soapbox Engage Integration User.
- Find the Account record type settings.
- Make your organization's appropriate Person Account record type available.
- Configure the applicable default record type.
- Click Save.
Can't find Account record types?
Salesforce's Enhanced Profile User Interface may display record type settings differently.
To switch temporarily to the original interface:
- In Setup, search for User Management Settings.
- Locate Enhanced Profile User Interface.
- Turn it off.
- Return to the Soapbox Engage Integration User profile.
- Look for Record Type Settings → Accounts.
You can restore the enhanced interface afterward.
If the Account record type is still unavailable, contact your Salesforce administrator or Salesforce Support to investigate the profile or license configuration.
Step 10: Confirm Nonprofit Cloud Fundraising configuration
In addition to Integration User permissions, your Salesforce administrator should verify that Fundraising is configured with the organization-level settings needed by the Fundraising Business API, including applicable donor matching, gift designation, and duplicate-management settings.
These settings are managed in Salesforce and aren't granted through Soapbox Engage permission sets.
Part 4: Restrict access using IP addresses
Restricting the Integration User to Soapbox Engage's authorized server IP addresses adds protection against unauthorized use of the account.
Step 11: Configure Login IP Ranges
- In Salesforce Setup, search for Profiles.
- Open Soapbox Engage Integration User.
- Find Login IP Ranges.
- Click Add IP Ranges or New.
- Add the following Soapbox Engage public IP addresses, each as a separate range, one at a time. These IP addresses represent Soapbox Engage's authorized Salesforce integration servers. For each individual IP address, use the same value for both the start and end of the range.
| Start IP Address | End IP Address | Description |
|---|---|---|
18.224.131.69 |
18.224.131.69 |
Soapbox Engage |
18.222.57.245 |
18.222.57.245 |
Soapbox Engage |
3.128.138.191 |
3.128.138.191 |
Soapbox Engage |
- Click Save after adding each entry. You may get a warning when adding an IP address. Follow the instructions to check a box to allow the save to continue successfully.
Important: If your organization uses Salesforce authentication processes or security policies that require additional IP addresses, review the requirements with your Salesforce administrator before applying restrictions.
Login IP Ranges versus Network Access
Profile Login IP Ranges control which IP addresses can authenticate using the assigned profile.
Network Access, configured separately under Salesforce Setup, identifies trusted networks. It isn't a substitute for profile-based Login IP Ranges. Our recommended setup process does not cover this.
Part 5A: Connect using traditional Salesforce credentials
Complete this section if your Soapbox Engage account uses a Salesforce username, password, and security token.
Step 12A: Configure traditional API authentication permissions
For traditional Salesforce API authentication, open the Soapbox Engage API Access permission set:
- Navigate to Setup → Permission Sets.
- Open Soapbox Engage API Access.
- Select System Permissions.
- Click Edit.
- Locate Use Any API Auth, if required for your organization's supported traditional API login method.
- Enable it and click Save.
Configure password expiration
For traditional integrations, password expiration can interrupt Soapbox Engage's Salesforce connection until its stored credentials are updated.
To help prevent unexpected interruptions:
- In the same permission set, open System Permissions.
- Click Edit.
- Locate Password Never Expires.
- Enable it if available and permitted by your organization's security policies.
- Click Save.
We recommend Password Never Expires for traditional Soapbox Engage integrations when permitted by your organization's security policies.
This helps maintain reliable API communication without unexpected password-expiration interruptions. Your organization should still maintain a secure credential rotation process and promptly replace credentials if compromise is suspected.
Step 13A: Obtain the Salesforce credentials
For traditional connections, you'll need:
- Salesforce username
- Salesforce password
- Salesforce security token, when required
Use your organization's approved Salesforce administrator procedures to initialize the Integration User's password and obtain the security token.
If a security token reset is needed, coordinate with your Salesforce administrator and the organizational mailbox receiving the Integration User's Salesforce notifications.
Salesforce may require temporarily removing the **Login IP Ranges** configured on the Integration User's Profile before the security token can be reset. Additionally, the **API Only User** permission may prevent access to the security token reset option.
After obtaining the new security token, restore the Profile's Login IP Ranges to the authorized Soapbox Engage IP addresses and update the credentials in Soapbox Engage as needed.
For security, minimize the time during which IP restrictions are removed.
Step 14A: Connect Soapbox Engage
- Sign in to Soapbox Engage administrator interface.
- On the control panel, go to the Salesforce.com Settings module on the right side of the screen.
- Enter the Integration User's Salesforce credentials.
- Save the connection.
For detailed instructions, see:
Adding or updating your Salesforce credentials in Soapbox
Ongoing security recommendations for traditional Salesforce credentials
- Restrict the Integration User to Soapbox Engage's authorized IP addresses.
- Use a unique password not shared with other users or applications.
- Rotate credentials according to your organization's security policies.
- Review the Integration User's permissions periodically.
- Update your Soapbox Engage account immediately whenever the user's password or security token changes.
Part 5B: Connect using OAuth
This part is required for the Soapbox Engage Nonprofit Cloud integration with the Soapbox Engage Donations app.
Step 12B: Find the Soapbox Engage Connected App
- In your Salesforce org, navigate to Setup.
- In Quick Find, search for Manage Connected Apps.
- Select Manage Connected Apps.
- Look for Soapbox Engage.
If the app isn't listed, you will need to initiate the connection from the Soapbox Engage administrator interface. Do not create a replacement Connected App unless specifically instructed by Soapbox Engage.
Step 13B: Grant Connected App access to the Integration User
You've already created the Soapbox Engage API Access permission set. Now you need to grant it access to the Connected App:
- Navigate to Setup → Permission Sets.
- Open Soapbox Engage API Access.
- Select Assigned Connected Apps.
- Click Edit.
- Move Soapbox Engage to the enabled applications list.
- Click Save.
- Confirm that the permission set is assigned to Soapbox Engage Integration.
This authorizes the Integration User through its permission set rather than granting Connected App access to an entire profile.
Step 14B: Restrict the Connected App to approved users
We recommend allowing only explicitly authorized users to connect through the Soapbox Engage Connected App.
- Open Setup → Manage Connected Apps.
- Find Soapbox Engage.
- Select Edit Policies.
- Under OAuth Policies, locate Permitted Users.
- Select Admin approved users are pre-authorized.
- Click Save.
This ensures that Salesforce administrators control which users can authorize Soapbox Engage.
Important: Changing this policy on an existing integration can revoke OAuth tokens and require reconnection. Plan the change with your Salesforce administrator.
Step 15B: Review the Connected App IP policy
- Open Setup → Manage Connected Apps → Soapbox Engage and click Edit Policies
- Find IP Relaxation, and set it to Enforce IP restrictions
Important: Do not enable Lock sessions to the IP address from which they originated solely for Soapbox Engage.
Step 16B: Authorize Soapbox Engage
- Sign in to you Soapbox Engage administrator interface.
- On the Control Panel, on the right side, find the Salesforce Nonprofit Cloud Settings module.
- Select Sandbox for sandbox connections, and Production for production connects to your Salesforce org.
- Click Connect.
- Follow the Salesforce authorization process using the dedicated Soapbox Engage Integration user (ensure that the user displayed is truly the integration user, and if not, follow the "Not you?" link to change to the integration user you created earlier.
- When returned to the Soapbox Engage administrator interface, on the right side under Salesforce Nonprofit Cloud Settings, confirm that the connection is successful and is using the appropriate Salesforce integration user. If not, start over again on the connection.
Already enforcing Login IP Ranges on every request? Before initiating the OAuth connection, read Part 6 below. You may need to temporarily authorize the IP address of the person completing the Salesforce login.
Part 6: Advanced security — Enforce Login IP Ranges on Every Request
Optional but strongly encouraged advanced security configuration
Salesforce provides an organization-wide security setting named Enforce login IP ranges on every request. When enabled, Salesforce applies profile-based Login IP Ranges to subsequent requests, including API requests. This provides important additional protections.
Important: This setting affects the entire Salesforce organization
Although the setting is enabled organization-wide, it enforces each user's profile-based Login IP Ranges. Users whose profiles don't have Login IP Ranges configured generally aren't restricted by this setting.
Before enabling it, confirm whether other profiles have IP restrictions and whether those users or integrations could be affected.
Step 17: Enable continuous IP enforcement
If your organization does not already have this setting enabled, we recommend establishing the Soapbox Engage OAuth connection first, as listed previously.
Once the connection is established:
- Verify that the Soapbox Engage Integration User profile includes the three authorized Soapbox Engage server IP addresses.
- Navigate to Salesforce Setup.
- Search for Session Settings.
- Find Enforce login IP ranges on every request.
- Enable the checkbox.
- Click Save.
- Return to Soapbox Engage.
- Test an operation that retrieves or updates Salesforce data.
- Verify that automatic OAuth token refreshes continue working.
Important: A successful API request using an existing access token doesn't necessarily prove that a future token refresh will succeed. Verify the refresh process before considering the configuration complete.
If the integration stops working, review the profile's IP ranges and Connected App policies with your Salesforce administrator.
Step 18: Connecting or reconnecting when enforcement is already enabled
If Enforce login IP ranges on every request is already enabled, the person connecting Soapbox Engage may need to temporarily add their own public IP address to the Integration User profile.
This is because the Salesforce login and authorization process may originate from the person's browser rather than a Soapbox Engage server.
A. Find your public IP address
On the computer you'll use to complete the Salesforce authorization:
- Open a browser.
- Visit WhatIsMyIP.com.
- Locate your public IPv4 address.
- Copy the address.
B. Temporarily add your IP to the Integration User profile
- Sign in to Salesforce as an administrator.
- Navigate to Setup → Profiles.
- Open Soapbox Engage Integration User.
- Find Login IP Ranges.
- Click Add IP Ranges or New.
- Enter your public IP address in both the Start IP Address and End IP Address fields.
- Click Save.
Do not remove the three Soapbox Engage server IP addresses.
C. Connect Soapbox Engage
- Sign in to your Soapbox Engage administrator interface.
- On the right side of the control panel in the Salesforce Nonprofit Cloud Settings being the sign in process again using the dedicated Salesforce Integration User.
- Complete authorization.
- Verify that Soapbox Engage reports a successful connection.
D. Remove your temporary IP address
After completing the connection:
- Return to Salesforce Setup → Profiles.
- Open Soapbox Engage Integration User.
- Locate Login IP Ranges.
- Delete the temporary range containing your public IP address.
- Confirm that only the authorized Soapbox Engage server IP addresses remain.
E. Verify the connection
Once your temporary IP address has been removed:
- Return to Soapbox Engage.
- Perform a test operation that integrates with Salesforce.
- Confirm that the operation succeeds.
Important: Test this whole process in your Salesforce environment before relying on it for production reconnections. If the integration fails after removing the temporary IP, review the Connected App's IP Relaxation policy and the Salesforce session settings.
If your organization later needs to reconnect Soapbox Engage, repeat the temporary-IP procedure when required.
Avoid session IP locking
Do not confuse Enforce login IP ranges on every request with Lock sessions to the IP address from which they originated. These are separate Salesforce controls.
Soapbox Engage uses multiple authorized servers. Binding a Salesforce session to one specific originating IP can interrupt requests made by another approved Soapbox Engage server. Do not enable the Lock sessions to the IP address from which they originated.
Part 7: Maintaining and Securing Your Salesforce Connection
Your Salesforce Integration User should be reviewed regularly, even after the initial setup is complete. In particular, we recommend periodically reviewing permissions, rotating credentials where appropriate, and revoking sessions or tokens that are no longer needed.
Important: The procedures differ depending on whether your Soapbox Engage account uses traditional Salesforce credentials or OAuth.
Step 19: Rotate credentials for traditional integrations
If your Soapbox Engage connection uses a Salesforce username, password, and security token, changing those credentials requires updating Soapbox Engage.
We recommend coordinating credential rotation with your Salesforce administrator to minimize interruptions.
- Sign in to Salesforce as an administrator.
- Navigate to Setup → Users → Users.
- Open Soapbox Engage Integration.
- Use Salesforce's password reset process to establish a new password.
- Reset the user's Salesforce security token if required.
- Sign in to Soapbox Engage administrator interface .
- Open the Salesforce integration configuration on the right side of the Control Panel.
- Update the stored Salesforce password and security token.
- Save the connection.
- Run a test operation to verify successful Salesforce communication.
See Adding or updating your Salesforce credentials in Soapbox.
Important: Resetting the password or security token can interrupt the integration until Soapbox Engage has been updated.
Revoke existing sessions after credential changes
When rotating credentials, we strongly advise revoking the Integration User's existing Salesforce sessions.
- In Salesforce, navigate to Setup → Users → Users.
- Open the Soapbox Engage Integration user.
- Look for the user's active session-management options.
- Use Salesforce's session revocation controls to terminate existing sessions as appropriate.
Your Salesforce administrator can also review Setup → Session Management to identify and terminate active sessions.
Revoking sessions may interrupt active API connections. Coordinate this step with your credential update and verify that Soapbox Engage can establish a new authenticated session afterward.
Security recommendation: whenever changing passwords, always additionally review and revoke any other authentication credentials or sessions associated with the user.
Step 20: Review and revoke OAuth connections
If your Soapbox Engage account uses OAuth, the Integration User's Salesforce password isn't the credential Soapbox Engage normally uses to access the API. Instead, Salesforce issues OAuth access tokens and refresh tokens.
For clarity, just changing the Integration User's Salesforce password does not necessarily revoke previously issued OAuth tokens.
To revoke OAuth access, use Salesforce's Connected App management tools.
Review existing OAuth connections
- In Salesforce, navigate to Setup.
- In Quick Find, search for Connected Apps OAuth Usage.
- Select Connected Apps OAuth Usage.
- Find Soapbox Engage.
- Select the user count or user details associated with the app.
- Review the users who have authorized Soapbox Engage.
Ideally, your dedicated Soapbox Engage Integration user should be the only Salesforce user authorized to use the integration. If you discover additional users who no longer need access, review those authorizations with your Salesforce administrator.
Revoke an OAuth authorization
If you need to revoke the Soapbox Engage Integration User's OAuth connection:
- Under Connected Apps OAuth Usage, find Soapbox Engage.
- Open the associated user usage details.
- Locate Soapbox Engage Integration.
- Click Revoke for the appropriate authorization.
- Confirm the revocation.
Warning: Revoking the active OAuth authorization prevents Soapbox Engage from continuing to use that authorization. You will need to reconnect Soapbox Engage through OAuth to restore the integration.
If you revoke all authorizations for the Connected App, you may affect other users or connections within your Salesforce organization.
Only use broader revocation options when specifically intended.
Reconnect Soapbox Engage
After revoking its OAuth authorization:
- Sign in to the Soapbox Engage administrator interface.
- On the Control Panel, in the right side of the screen, go to the Salesforce OAuth configuration
- Start the OAuth authorization process again.
- Authenticate using your dedicated Salesforce Integration User.
- Complete authorization.
- Verify that Salesforce communication has been restored.
If your organization has enabled Enforce login IP ranges on every request, follow the temporary-IP procedure in Step 18 before reconnecting.
When should OAuth tokens be revoked?
We recommend revoking and reauthorizing the Soapbox Engage connection when:
- You suspect that an OAuth access token or refresh token has been compromised.
- An unauthorized user has been granted access to the Connected App.
- You are replacing the Integration User.
- Your organization is intentionally retiring or rebuilding the Salesforce integration.
- Your Salesforce security team determines that existing authorizations should no longer be trusted.
Step 21: Periodically review permissions
We recommend periodically reviewing the Integration User's access, particularly when your Soapbox Engage configuration changes.
At minimum, review:
- Assigned permission sets and permission set licenses.
- Object and field permissions.
- Access to custom Salesforce objects and fields.
- Login IP Ranges.
- Connected App authorization policies, for OAuth connections.
- Active sessions and OAuth authorizations.
- Whether the Integration User is used exclusively by Soapbox Engage.
Remove permissions and authorizations that are no longer required.
Part 8: Troubleshooting
If your Soapbox Engage integration isn't working as expected, use the following table to identify the most likely cause.
| Problem | What to check |
|---|---|
| Connection fails during OAuth authorization | Connected App authorization, profile Login IP Ranges, IP Relaxation, and Session Settings |
| User isn't approved for Connected App access | Permitted Users policy and Assigned Connected Apps |
| Salesforce API access is denied | API permissions, object permissions, field permissions, and license assignments |
| Soapbox Engage cannot find records | Salesforce sharing settings, record ownership, field access, and integration configuration |
| NPC donation fails with PersonAccount record type error | Person Account record type availability and default record type configuration |
| OAuth connection works but Fundraising operations fail | Fundraising Access, NPC configuration, required record types, and API response errors |
| Traditional API login fails | Username, password, security token, IP restrictions, authentication permissions, and Salesforce login configuration |
| Integration fails after enabling continuous IP enforcement | Profile Login IP Ranges, Connected App IP Relaxation, and token refresh behavior |
| Campaign creation fails | Marketing User checkbox and Campaign object permissions |
| Connection stops working after password rotation | Confirm Soapbox Engage has the updated password and security token |
| OAuth connection stops working after token revocation | Reauthorize Soapbox Engage using the Integration User |
Where to look for errors
Salesforce Login History
Navigate to Setup → Login History to review authentication attempts and login failures.
Salesforce Debug Logs
Navigate to Setup → Debug Logs to inspect supported Salesforce execution and automation activity.
Not every API request produces an Apex debug log (such as donation processing with the Salesforce Nonprofit Cloud), so the absence of a debug log doesn't necessarily mean Salesforce never received the request.
Never send Salesforce passwords, security tokens, OAuth access tokens, or refresh tokens in support requests.
Final security checklist
Before considering your Salesforce integration setup complete, confirm the following:
-
A dedicated Salesforce Integration User has been created.
-
The user has a dedicated API-only Integration User profile.
-
API Enabled and API Only User are enabled.
-
Marketing User is enabled.
-
The Salesforce API Integration permission set license is assigned.
-
The Soapbox Engage API Access permission set is assigned.
-
Read, Create, and Edit permissions are configured for the objects Soapbox Engage needs.
-
Required standard and custom field permissions are configured.
-
The Integration User profile contains Soapbox Engage's three authorized IP addresses.
-
For Salesforce Nonprofit Cloud (NPC) for fundraising, the Fundraising Access permission set and license are assigned.
-
For Salesforce Nonprofit Cloud (NPC) for fundraising, required Person Account record types and Fundraising configuration have been verified.
-
For OAuth integrations, the Soapbox Engage Connected App is restricted to approved users.
-
Unnecessary administrative permissions haven't been granted.
-
The Salesforce connection and a test transaction have been verified.
-
The organization has reviewed optional continuous IP enforcement.
-
The organization has a process for periodically reviewing and rotating integration credentials.
-
The organization understands how to revoke existing sessions and OAuth authorizations when necessary.
Additional Salesforce documentation
- Give Integration Users API Only Access
- Assign Fundraising Permission Sets in Nonprofit
- Manage OAuth Access Policies for a Connected App
- Manage Current OAuth Connected App Sessions
- Revoke OAuth Tokens Programmatically
- Restrict Login IP Addresses in Profiles
- Connected App IP Relaxation and Continuous IP Enforcement