Skip to contentIntroducing the Integration Factory
Back to Blog
Integration

How to Set Up a Salesforce External Client App for Nango

Sunny Chauhan

Nango needs your own Salesforce client ID and secret, and on Salesforce those come from an External Client App (ECA). If you only connect your own org, a local ECA built in App Manager is enough. If your customers connect their orgs, the ECA has to be packaged and installed in each customer's org, because Salesforce says local ECAs "are available only on the org where you create them" (Salesforce Developers).

That second case is the one most SaaS teams are in, and it is where Nango setups stall. Nango handles the OAuth flow, token refresh and syncs. The Salesforce side still needs a packaged app built from a Dev Hub and a namespace. Once more than two customer production orgs use it, Salesforce's partner OAuth controls apply too. Appnigma's integration infrastructure covers this part of the work, with "app registration and authorization with infra built for the systems your customers use." Its free External Client App tool hands back a client ID, a secret and a managed package install link without you creating a Dev Hub.

Updated October 2026. Checked against Nango's Salesforce setup guide, Salesforce's ISVforce Guide and the second-generation packaging docs. The earlier version dated the connected app restriction to Winter '26, said the whole setup takes two minutes and recommended non-expiring refresh tokens without the partner rules. This update adds when you need a packaged app, the OAuth controls Salesforce now requires of partners, and the errors customers hit after install.

How do customers connect their own Salesforce org through Nango?

Customers connect through a packaged ECA installed in their org, and a local app only works for your own. The choice depends on whose org signs in, not on how many users you have. Nango's guide lists the same two distribution options, "Local" for "use only inside your own Salesforce org" and "Packaged" for "distributing your app to other Salesforce orgs" (Nango).

Your situationECA you needWhat it takesWho sets policies
Internal tool, your own org onlyLocal ECAApp Manager in your org, about 15 fieldsYou
Customers connect their own orgsPackaged ECA in a managed packageA Dev Hub, a namespace org, a package version, an install in each customer orgEach customer's admin
You want your own AppExchange listingPackaged ECA in your namespaceEverything above plus security reviewEach customer's admin

The packaged route needs two orgs if you build it yourself. Nango's guide says "you cannot have both Dev Hub enabled and register a namespace in the same organization," and Salesforce's own namespace steps start with "Sign up for a new Developer Edition org" (Salesforce 2GP namespaces).

One client ID and secret serve every customer org that installs the package. Salesforce keeps consumer credentials out of the package, so they stay in the org where you built the app, and deleting the ECA there breaks every installed copy (Package an External Client App). Treat that source org as production infrastructure, with named owners and no shared admin login.

The Salesforce settings Nango expects

Every value below comes from Nango's Salesforce setup guide or its provider configuration, which is what Nango actually sends to Salesforce.

SettingValueWhy it matters
Callback URLhttps://api.nango.dev/oauth/callback, or your custom callbackSalesforce rejects the flow when the redirect URL differs
OAuth scopesAt least api and refresh_token, offline_accessNango requests offline_access by default
FlowEnable Authorization Code and Credentials FlowThe flow Nango runs
SecurityKeep "Require secret" for both flows and "Require PKCE" checkedMatches Salesforce's partner rules below
Login hostlogin.salesforce.com, or the customer's My Domain hostSandboxes use the separate Salesforce Sandbox integration on test.salesforce.com

Nango sends prompt=consent on every Salesforce authorization, so users see the approval screen each time they connect, even when they approved before. The hostname field is optional, and Nango's validation rejects lightning.force.com addresses. Customers who paste the URL from their browser tab get an error until they use the my.salesforce.com host instead.

Salesforce returns a different API base URL per org. Nango "automatically retrieves the instance_url from Salesforce and stores it in the connection config," and its proxy uses it for you (Nango).

Getting the client ID and secret without building the package

Building the packaged ECA by hand means creating the app in a Dev Hub, retrieving its metadata with the Salesforce CLI, and cutting a managed package version. Nango's guide walks through eleven steps and stops at sf package version create. Add a promote step before you send a link to customers, because "Beta versions can be installed in only scratch orgs and sandboxes" (Salesforce 2GP). Appnigma's free External Client App tool does that work for you in four screens.

You sign in with a work email and a six digit code, then enter three things. The app name is what users see on the Salesforce consent screen, so use your product name. Redirect URLs take one entry per environment, and you paste Nango's callback here. Scopes come as presets.

PresetScopesFits
Data onlyapi, refresh_token, webBackend syncs that never need to know who the user is
Data plus sign-inAdds openid, profile, email, offline_accessUsers also sign in to your product with Salesforce
Full accessAdds address, phone, content, custom_permissions, wave_api, eclair_apiDemos only, narrow it before customers connect

Data only already meets Nango's minimum, because refresh_token and offline_access are the same Salesforce permission. Pick the smallest preset your syncs use. An enterprise admin reviewing an install will ask why an integration that moves Accounts wants CRM Analytics and Maps access.

Filling in the form takes a couple of minutes. Provisioning then runs in the background and can take around 20 minutes. The credentials screen shows the client key (Salesforce calls it the consumer key), the secret behind a Reveal control, and the managed package install link once the package is ready for production orgs. The secret is shown once, so have your secrets manager open before you reveal it. Salesforce's staged secret rotation covers local apps only, and its docs say "This workflow doesn't apply to packaged external client apps." Redirect URLs and scopes stay editable, and a scope change builds a new package version. The app name can't be changed later.

Paste the credentials into Nango and connect a test org

In Nango, open the Salesforce integration settings, paste the client ID and secret, save and run a test connection against an org that has the package installed. A customer org without the install has no copy of the app to authorize.

Set your custom callback before real customers connect. Nango's version is an endpoint on your domain that "308-redirects to https://api.nango.dev/oauth/callback," registered with Salesforce and then set in Nango's Environment Settings, once per environment (Nango auth guide). Nango warns that changing it later "can break new authorization or reconnect flows until the provider and Nango settings match."

Nango also offers its own managed Salesforce app for testing. It works, but "the consent screen shows Nango, not your product," and "provider marketplaces require your own app" (Nango auth guide). Use it to prototype, then switch to your ECA before the first customer.

What changes once more than two customer orgs use the app

Salesforce's partner OAuth rules apply to any ECA "provided or created by the Partner, and in use by more than two customer production orgs" (ISVforce Guide). A SaaS product that connects customer orgs through Nango crosses that line with its third customer. Every control had a compliance date of May 11, 2026, and Salesforce says non-compliance "may result in" AgentExchange de-listing or suspension of the app's access. The four controls map onto a Nango integration like this.

ControlSalesforce's ruleWhat to check in Nango
PKCERequired for confidential clients, sent with the client secretNango's guide keeps "Require PKCE" on, so confirm the box is ticked on your app
Refresh token rotationThe client must "capture the new refresh token" on each refreshTest a refresh in a sandbox before you enable it, because it can't be turned off
30-day idle TTL"Salesforce invalidates the idle refresh token after 30 days"Nango refreshes "at least once every 24 hours," so active connections stay alive
Refresh token IP allowlistUp to 256 addresses across all rangesNango publishes four outbound IPs that "may change as we scale"

New apps don't get a choice on three of them. Salesforce's Summer '26 release note says "Starting in July 2026, Salesforce enforces OAuth security controls for new external client apps." Refresh token rotation is "auto-enabled, locked, and grayed out" on new apps. PKCE has been auto-enabled since August 2026, and the 30-day limit applies to them too (release note). The date that counts is when the app was created in the source org. Nango's docs don't say how it stores a rotated refresh token or handles two refreshes at once, so run a refresh against a sandbox connection and confirm the second one still works before customers connect.

Two of these need care on older apps. Rotation can't be disabled once on, and after you self-attest, Salesforce says "the security controls are locked and can't be disabled." The IP allowlist would pin token refresh to Nango's published addresses (Nango security), so a Nango IP change would block every refresh until you update the range. Decide on that control with your security team, not during a deadline week.

The 30-day limit is also arriving for everyone. Salesforce's Winter '27 release expires refresh tokens left unused for 30 days, in sandboxes from October 21, 2026 and in production from November 4, 2026 (release note). Tokens already idle for more than 30 days at enforcement expire straight away, and installed copies of packaged apps are covered. Nango's daily refresh keeps live connections inside that window. A connection you pause for a month, or a customer trial that sits idle, will need the user to reconnect.

The Refresh Token Policy you set is only a default once the app is packaged. Salesforce says packaged default values "display in the policies tab on a distributed external client app and can be edited by admins" (Salesforce Canvas guide). Nango recommends "Refresh token is valid until revoked," but a customer's admin can shorten it in their org. Monitor refresh failures per connection, because one customer's policy change looks like your bug.

Can you still use a connected app with Nango?

Only if you already have one. Salesforce's knowledge article is titled "New connected apps can no longer be created in Spring '26," and the ISVforce Guide says "you can't create new Connected Apps. Use ECAs instead" (ISVforce Guide). The article says creation is blocked "through both API and UI, with the exception of package installation" (Salesforce Help). Existing connected apps keep working.

To move a connected app over, App Manager offers "Migrate to External Client App" for eligible apps, meaning local ones that don't use the username-password flow (Nango). The old app becomes read only. A migrated local app still only works in your own org, so customers' orgs still need the packaged route.

Errors customers hit after they connect

These are the failures that show up once real customer orgs connect, not during your own test.

  • redirect_uri_mismatch. The callback on the ECA differs from what Nango sends. Common causes are a trailing slash, a callback copied from another Nango environment, or a custom callback set in Nango but not added to the app.
  • Cross-org OAuth flows are not supported for this external client app. A user from another org tried to authorize a local ECA. Unified.to's multi-org guide reports this exact message, and the fix is the packaged app installed in that org.
  • invalid_client_id. Nango's troubleshooting note says to "ensure your (developer) user password does not contain special characters."
  • Hostname rejected. The customer entered a lightning.force.com address. Ask for the my.salesforce.com host.
  • Connection dies after a quiet month. The 30-day idle limit expired the refresh token. The user reconnects, and a Nango refresh-failure webhook lets you prompt them first (Nango token refreshing).
  • Refresh works for most customers and fails for one. That customer's admin changed the app's refresh token or permitted user policy in their org.

When to build the app yourself and when to bring in help

Build a local ECA yourself if Nango only ever connects your own org. It is a short setup in App Manager. For customer orgs, a packaged ECA from Appnigma's free External Client App tool is the quickest start, and teams that want their own namespace and AppExchange listing need the package built under their own Dev Hub. Appnigma's marketplace apps work covers that route with "listing preparation, and review support." If you are still choosing between Nango and other Salesforce integration tools, the Salesforce ECA work is the same whichever one you pick, because customer orgs still need your packaged app installed.

Frequently Asked Questions

Does Nango work with Salesforce sandboxes?

Yes. Nango has a separate Salesforce Sandbox integration that signs in through test.salesforce.com, so configure it with its own credentials.

Which scopes does Nango need for Salesforce?

At minimum api plus refresh_token, offline_access. Add openid, profile and email only if users sign in to your product with Salesforce.

Where do I find the client ID and secret for an ECA I built myself?

On the app's Settings tab, under OAuth Settings, click Consumer Key and Secret and verify your identity. The consumer key is the client ID.

Can Appnigma set up the Salesforce side of our Nango integration?

Yes. The free External Client App tool provisions a packaged ECA and returns the credentials and install link, and Appnigma's integration infrastructure handles app registration and authorization for customer integrations.

About the author

Sunny Chauhan is the co-founder and CEO of Appnigma AI, which builds and maintains customer integrations and native Salesforce and HubSpot apps for B2B SaaS teams. Before Appnigma, he was on Salesforce's AppExchange team, where he worked with more than 300 SaaS partners. He has spent close to a decade on the Salesforce platform, including work at Zennify, and holds Salesforce certifications including Platform Developer II, Platform App Builder, Administrator, Data Cloud Consultant, and AI Associate.

Sources

  1. Nango Docs, How to set Salesforce up with Nango
  2. Nango Docs, Auth guide (custom callback URL, Nango-managed OAuth apps)
  3. Nango Docs, Token refreshing and validity
  4. Nango Docs, Security (network access)
  5. Nango, providers.yaml on GitHub (Salesforce and Salesforce Sandbox entries)
  6. Salesforce Developers, ISVforce Guide, Secure Your Connected Apps and External Client Apps
  7. Salesforce Help, New connected apps can no longer be created in Spring '26
  8. Salesforce Help, Package an External Client App
  9. Salesforce Help, Winter '27 release note, refresh token idle time-to-live
  10. Salesforce Help, Summer '26 release note, OAuth security controls on for new external client apps
  11. Salesforce Developers, Second-Generation Managed Packaging, Get Ready to Promote and Release a Package Version
  12. Salesforce Developers, Second-Generation Managed Packaging, Create and Register Your Namespace
  13. Salesforce Developers, Canvas Developer Guide, Package the External Client App for Canvas
  14. Salesforce Developers, B2B Commerce, Configure External Client App (local vs packaged)

Which integration is your next deal waiting on?

Bring the customer requirements and your current setup. Get a clear scope and delivery timeline to take back to them.