Skip to main content
Contact Support

Migrating your Formstack for Salesforce connection to an External Client App

Ron S.
Updated

Why this change is happening

Salesforce is updating how third-party apps like Formstack connect to your Salesforce org. The older connection method (Connected Apps) is being replaced across the Salesforce platform by a newer, more secure standard called External Client Apps (ECA).

To keep your Formstack integration compliant with Salesforce's security requirements — and to keep your forms and data flowing without interruption — your org needs to move to this new connection type. It's a one-time action for a Salesforce administrator, and once it's done, day-to-day form use is exactly the same. There's an added benefit for you too: on the new connection, future Formstack updates can be applied smoothly without requiring you to re-authorize each time.

What to expect

What you need to do A one-time migration in Formstack Admin Settings, performed by a Salesforce admin.
How long it takes A couple of minutes.
Downtime None. Your current connection keeps working until the new one is confirmed.
After migration Nothing changes in how you build or use forms.

Before you begin

  • Make sure you're on the latest Formstack package, 4.162.1. If you're on an earlier version, upgrade first. (Upgrading the package alone does not complete the migration — you'll still do the step below.)
  • You'll need a Salesforce administrator who can open Formstack Admin Settings.
  • Allow pop-ups for your Salesforce domain in your browser — the authorization step opens in a pop-up window.
  • The same admin who starts the migration must be the one who completes the approval step.

How to migrate

Step 1 — Find the migration banner

Open Formstack from your Salesforce App Launcher. If your org still needs to migrate, you'll see a banner: Migrate to External Client App. Click Go to Admin Settings (or open Admin Settings directly).

Step 2 — Start the migration

In Admin Settings, click Migrate to External Client App on the banner. Allow the pop-up if your browser prompts you. You may briefly see a message that the migration is finishing — don't close the pop-up while it runs.

Step 3 — Approve access in Salesforce

In the pop-up, sign in as the same Salesforce user who started the migration if you're asked to. On the Allow Access? screen, review the permissions and click Allow.

Step 4 — Wait for confirmation

Salesforce will finish setting up the new connection. When it's done, you'll see a green success message confirming your Formstack connection now uses the External Client App, and the migration banner will disappear.

Step 5 — Confirm it worked

  • The Migrate to External Client App banner is gone.
  • Your forms load without any authentication errors.
  • Submit a test entry on one of your forms and confirm it appears in Salesforce.

Step 6 - Configure the External Client App policy

You may see a warning that the Forms For Salesforce External Client App is not configured to require admin-approved users. The warning explains that your Formstack connection may be lost during a future upgrade unless you update the policy.

External Client App policy warning

To update the policy:

  1. In Salesforce, go to Setup > Apps > External Client Apps > External Client App Manager.
  2. Open the Forms For Salesforce External Client App.
  3. Under OAuth Policies, set Permitted Users to Admin approved users are pre-authorized.
Select Admin approved users are pre-authorized
  1. If Salesforce displays the Confirm permitted user policy warning, click OK.
Confirm permitted user policy message
  1. Under App Policies, find Select Profiles.
  2. Select the Salesforce Profile assigned to the Primary User shown in Formstack Admin Settings. This is the integration user whose Profile must be authorized.
  3. Move that Profile to Selected Profiles.
  4. Click Save.
Select the Primary User Salesforce Profile

Important: We recommend authorizing the integration user through their Profile, not through a Permission Set. The confirmation message warns that existing users may be denied access. During this process, you can safely click OK, provided you select the Primary User’s Profile and save the policy before leaving the page.

Troubleshooting

How can I confirm that the migration succeeded?

  1. Open Formstack for Salesforce.
  2. Go to Admin Settings > User Management.
  3. Hover over the question mark next to the User Management heading.
  4. Review the Connection type shown in the tooltip.

A successful migration displays External Client App (v3) as the connection type.

External Client App connection type in User Management

I see “Authentication failed: organization mismatch.”
This error usually means you are signed in to more than one Salesforce org in your browser.

  1. Sign out of every Salesforce org currently open in your browser.
  2. Sign in only to the Salesforce org you want to migrate.
  3. Return to Formstack Admin Settings and retry the migration.
Authentication failed organization mismatch error

The banner came back after I clicked Migrate.
The migration may not have finished, or the pop-up was blocked or closed too early. Allow pop-ups for your Salesforce domain, then click Migrate to External Client App again and complete the Allow step — making sure you're signed in as the same user who started it.

I got an error saying a different user needs to authorize.
The approval must be completed by the same Salesforce user who started the migration. Start again from Admin Settings and complete the pop-up as that same user.

I got an error that the app is blocked by an admin.
Your Salesforce admin needs to authorize the Formstack External Client App for your user. If you're not the org admin, ask them to enable it, then retry the migration. If you are the admin and need help with this, contact Formstack Support.

The migration succeeded but my forms still aren't working.
Contact Formstack Support and let us know: that you used Migrate to External Client App (not Reset OAuth token), any error text you saw, and that you've completed the migration. We'll take it from there.

I see the error “Authentication failed during the External Client App token exchange” when I try to migrate.
This usually means your Salesforce user’s IP address is restricted and hasn’t been added to the allowed IP range.

To confirm:

  1. In Salesforce, go to Setup > Login History.
  2. Find your login activity and check the Status column.
  3. If the status shows Restricted IP, your IP address is being blocked.

To resolve the issue, add the IP address shown in Login History to the allowed range for the Salesforce profile assigned to that user:

  1. In Salesforce, click the gear icon > Setup.
  2. In the Quick Find box, search for and select Profiles.
  3. Select the profile assigned to the user who received the error, then click Edit.
  4. Scroll to Login IP Ranges and click Add IP Range.
  5. Enter the IP address or range you want to allow, such as 155.226.157.253 or 155.226.157.253 - 155.226.157.255.
  6. Click Save, then retry the migration.

Frequently asked questions

Do I need to upgrade the package first?
You need to be on the latest package, 4.162.1, to migrate. Upgrading the package on its own doesn't move your connection — you'll still complete the Migrate to External Client App step in Admin Settings.

Will "Reset OAuth token" migrate me?
No. Reset OAuth token only renews your current connection. Use Migrate to External Client App to move to the new connection type.

Does this change my Primary User?
No, not unless you separately choose to reassign it.

What happens if the migration fails partway through?
Nothing breaks. Your existing connection stays active until the new one is fully confirmed, so there's no interruption to your forms.

Related articles