Soapbox Engage connects to your Salesforce organization with OAuth: you sign in to Salesforce once from Soapbox and approve the Soapbox Engage app, and Soapbox keeps that connection without storing your Salesforce password. Salesforce has announced that it will stop accepting sign-in with a username, password and security token in its Summer '27 release, so sites that still use a password should switch before then.
Before you begin
- Install the Soapbox Engage app in Salesforce. A Salesforce administrator does this once in each organization you connect, sandboxes included. In Setup, search for Connected Apps OAuth Usage, find Soapbox Engage, click Install, and confirm. If it already shows Uninstall, it's installed and there's nothing to do. If Soapbox Engage isn't listed yet, click Connect to Salesforce once from Soapbox, then reload the Salesforce page. Without this step, Salesforce may stop the connection on its own error page.
- Choose the Salesforce user Soapbox will act as. Soapbox creates and updates records as this user, so their permissions and field access decide what Soapbox can do. A dedicated integration user is recommended. See Using Salesforce Integration User Licenses with Soapbox Engage.
- Make sure the user can use the API. The user's profile or permission set needs API Enabled.
- Make sure the user can approve the Soapbox Engage app. If your organization limits which users can use connected apps, your Salesforce administrator needs to allow the Soapbox Engage app for this user's profile or permission set.
- Use one Salesforce user per Soapbox site. Salesforce limits how many active connections one user can approve for the same app, and approving more can quietly end an older connection on another site.
Which panel to connect
Your Control Panel can have two Salesforce panels:
| Panel | Connects |
|---|---|
| Salesforce.com Settings | Events, Forms, Directories, Petitions, Shop, the User Manager, campaign selection, and Donations Leads |
| Salesforce Nonprofit Cloud Settings | Donations and Auctions gifts in Salesforce Nonprofit Cloud |
If your site uses Salesforce Nonprofit Cloud for Donations and Auctions only, connect Salesforce Nonprofit Cloud Settings. If it uses any of the other apps, connect Salesforce.com Settings too, as the same Salesforce organization.
Connecting for the first time
- In the Soapbox administrator, open the Control Panel and expand Salesforce.com Settings.
- Leave Salesforce Account set to My Salesforce Account.
- Choose the Environment: Production, or Sandbox for a Salesforce sandbox.
- Click Connect to Salesforce.
- Sign in to Salesforce as the user you chose, and click Allow.
You return to the Control Panel with "Successfully connected to Salesforce". The panel shows Status Connected with OAuth, who Soapbox is Connected as, the Organization and the Environment. You can also connect from the Setup Assistant's Connect to Salesforce step or from the Salesforce Dashboard.
Switching from a username and security token
A site that signs in with a password shows "This site signs in to Salesforce with a username and security token. Salesforce stops accepting this sign-in in its Summer '27 release."
- Check the Environment, and click Switch to OAuth.
- Sign in to Salesforce and click Allow. Sign in to the same organization the site already uses: Soapbox refuses a different one, because records it has already linked belong to the current organization.
- If you sign in as a different user than the saved username, or Soapbox has no record of the site's organization, a page asks you to confirm. Click Switch to OAuth to continue, or Cancel to change nothing.
You see "Switched to OAuth." For the next 14 days the panel shows a Password sign-in box with the saved username and the date it ends, and a Switch back to password sign-in button. Use it if something stops working after the switch. After 14 days, Soapbox deletes the saved password and security token, and the site connects with OAuth only.
If you click Disconnect during those 14 days, Soapbox also deletes the saved password and security token straight away.
Updating a username, password or security token
Until you switch, you can still update the saved credentials in Salesforce.com Settings or on the Salesforce Dashboard. After a password change, Salesforce sends a new security token, so update both. Once a site connects with OAuth, it no longer uses a password.
Connecting a sandbox, then going live
You can connect a sandbox first to test, then connect production. A production organization, and a refreshed sandbox, count as a different organization, so when you connect, Soapbox shows "Connect to a different Salesforce organization?" with the current organization and the one you signed in to. Click Connect to (the new organization) to continue. Links to campaigns, contacts, products and events in the earlier organization stop working, so connect the organization you'll keep before you link records.
When the connection needs reconnecting
If Salesforce stops accepting the connection (for example, the user is deactivated, its access is revoked, or the app is no longer allowed), the panel shows Status Needs reconnecting since a date, with the user and organization it was connected to. Records aren't sent to Salesforce until you reconnect. Choose the Environment and click Reconnect to Salesforce.
Disconnecting
Click Disconnect and confirm. Soapbox revokes its access in Salesforce and stops sending records until you connect again.
If Salesforce refuses the connection
| Message | What to do |
|---|---|
| You chose Deny on Salesforce's page, so Soapbox was not connected. | Click Connect to Salesforce again and choose Allow. |
| Salesforce refused the connection because this user cannot use the API… | Ask your Salesforce administrator to turn on API Enabled for the user. |
| Salesforce refused the connection because your organization has not approved the Soapbox app… | Ask your Salesforce administrator to allow the Soapbox Engage app for the user. |
| You signed in to a different Salesforce organization… | When switching, sign in to the organization the site already uses. |
Some refusals appear on Salesforce's own page instead, and you don't return to Soapbox.
If that page shows OAUTH_APPROVAL_ERROR_GENERIC and its address includes app must be installed into org, the Soapbox Engage app isn't installed in your organization yet. A Salesforce administrator can install it:
- In Salesforce, open Setup and search for Connected Apps OAuth Usage.
- Find Soapbox Engage in the list, click Install, and confirm.
- Back in Soapbox, click Connect to Salesforce (or Switch to OAuth) again.
For any other refusal on Salesforce's page, ask your Salesforce administrator to check the user and the Soapbox Engage app's settings, then try again.
Checking the connection
Open Diagnostics. The Salesforce section shows whether the connection is working and who it signs in as.