Nango handles the OAuth dance, the token refresh and the syncs. What it does not do is create the Salesforce side of the connection for you. Every Salesforce integration in Nango needs your own client ID and secret, and on Salesforce those live in an external client app that somebody has to build first.
Nango documents that build honestly, and it is not short. If you only ever connect your own org, it is a web form. If you need to ship the integration to customers, Salesforce makes you run two separate Salesforce accounts, install the CLI, and cut a managed package version before you have a single credential to paste back.
This guide covers both: what the manual path actually involves, and how to get the same client ID, secret and managed package link in about two minutes instead.
Prerequisites
- A Nango account with a Salesforce integration, so you can copy its callback URL.
- A work email address. The external client app gets registered to it.
- If you are doing this the manual way: a Salesforce org on Professional, Performance, Unlimited or Developer edition, and the "Create, Edit, and Delete External Client Apps" permission. For packaged distribution, two orgs.
Why Nango asks for your own client ID and secret
Nango is deliberately not a middleman for your credentials. For anything heading to production you register your own OAuth app with the provider and hand Nango the keys, so the connection belongs to you rather than to a shared developer app.
On Salesforce that OAuth app is an external client app. It holds the scopes, the redirect URLs, and the client ID and secret Nango signs in with. Salesforce calls the client ID the consumer key, which is the first place people get confused when copying values between two dashboards.
Why it has to be an external client app, not a connected app
Nango's Salesforce guide is titled "Why External Client Apps only" for a reason. Salesforce is retiring the connected app as the way to build new integrations:
- In Winter '26, creating connected apps through the UI was turned off by default on new orgs.
- From Spring '26, that capability cannot be re-enabled without approval from Salesforce Support.
Existing connected apps keep working, and App Manager offers a "Migrate to External Client App" button for eligible ones, after which the old app becomes read only and all changes happen on the new one. But if you are wiring up Nango today, the external client app is the only sensible starting point.
Local or packaged: the fork that decides how much work this is
This is the decision that determines whether the manual path takes twenty minutes or most of a day, and it is easy to miss on a first read.
| Local distribution | Packaged distribution | |
|---|---|---|
| What it is for | Connecting your own Salesforce org | Shipping the integration to your customers' orgs |
| Salesforce accounts needed | One | Two, and they cannot be the same org |
| Salesforce CLI | Not needed | Required |
| Managed package | No | Yes, you cut the version yourself |
| Realistic effort | A web form | Dev Hub, namespace, CLI, package.xml, sfdx-project.json |
The two-account rule is a hard Salesforce limitation rather than a Nango one: you cannot have Dev Hub enabled and register a namespace in the same organisation. So packaged distribution means one org as the Dev Hub and a second org holding the namespace, linked through Namespace Registries.
If you are a SaaS company whose customers install your integration, you are on the packaged path whether you wanted to be or not.
What the manual path actually involves
For local distribution, Nango's documented steps are roughly: Setup, App Manager, New External Client App, fill in the basics, enable API and OAuth settings, set the callback URL, choose scopes, enable the Authorization Code and Credentials flow, leave the security defaults alone, and create it. Then reopen the app, go to Settings, scroll to OAuth Settings, click Consumer Key and Secret, verify your identity, and copy both values.
For packaged distribution, add all of this on top:
- Create a second Salesforce account and enable Dev Hub on the first.
- Register a namespace on the second account and link it to the Dev Hub through Namespace Registries.
- Install the Salesforce CLI.
- Authenticate the CLI with
sf org login web --set-default-dev-hub --alias my-dev-hub. - Generate a project with
sf project generate --name nango. - Create the managed package.
- Write a
package.xmldeclaring the metadata types. - Retrieve the external client app metadata with
sf project retrieve start. - Configure
sfdx-project.jsonwith the package ID and namespace. - Cut a version with
sf package version create --package <PACKAGE_ID>. - Hand the resulting install URL to your customers.
None of that is unreasonable. It is just a lot of setup standing between you and the two strings Nango actually needs.
Step 1: Copy the callback URL from Nango
Nango's default callback is https://api.nango.dev/oauth/callback, and it is documented on the Salesforce setup page.
Check your own integration settings rather than assuming, because Nango also supports a custom callback on your own domain. That is the one you want in production, since the Salesforce consent screen your customers see then shows your domain instead of Nango's.
Set the custom callback before real users connect. Changing it later means updating both the Salesforce app and Nango, and authorization breaks for anyone who tries in between.
Copy the value. Do not retype it. Salesforce compares the redirect URL on the authorization request against the stored one character for character, and a trailing slash is enough to fail it.
Step 2: Start your external client app
Go to the external client app provisioner and enter your work email. There is no password to create and no account form ahead of the product.
Step 3: Verify your email
A six digit code arrives by email. Keys are never emailed to you and are only ever shown in the app, which is the behaviour you want from anything handling OAuth secrets.
Step 4: Name the app and add the callback URL
The ECA name is not just a label. It is the name your users see on the OAuth consent screen, so pick something a customer will recognise as yours rather than test app 2. You get 40 characters.
Then paste the callback URL from Step 1 into the redirect URL field. You can add more than one, and the guidance in the form is to add one per environment, which is exactly how you keep staging and production on the same app. Every field here stays editable afterwards, so none of it is a one way door.
Step 5: Pick your scopes
Three scopes ship with every app: api, refresh_token and web. The other ten are yours to add, as a preset or one at a time.
| Preset | Count | Scopes added | Use it when |
|---|---|---|---|
| Data only | 3 | api, refresh_token, web | Backend syncs and scheduled jobs. Moves records and refreshes its own tokens, never learns who the user is |
| Data plus sign-in | 7 | Adds openid, profile, email, offline_access | People sign in to your app with their Salesforce account. The common choice |
| Full access | 13 | Adds address, phone, content, custom_permissions, wave_api, eclair_api | Fastest to get moving, worth narrowing before production |
Nango's own minimum is api plus refresh_token or offline_access. Data plus sign-in covers that and adds the identity scopes, which is why it is the default recommendation here.
Take the middle preset unless you know you need more, and the reason is commercial rather than technical. Enterprise Salesforce admins review what your app is asking for. A request for analytics, CMS content and maps that your integration never calls is the kind of thing that stalls in a customer security review. Ask for identity plus data and you will clear more approvals.
Step 6: Collect your credentials
The app is provisioned and you land on the credentials screen with three things:
- Client key, which is your OAuth
client_idand what Salesforce calls the consumer key. - Secret key, hidden behind a Reveal control and only shown in this session. Have somewhere safe ready to paste it before you click.
- A managed package install link, a standard
login.salesforce.com/packaging/installPackage.apexpURL, ready to hand to a customer who needs the app in their own org.
That managed package link is the part worth pausing on. On the manual path it is the output of steps 5 through 11 above.
Step 7: Paste the credentials into Nango
Back in Nango, open the Salesforce integration settings and paste the client ID and client secret into the OAuth configuration. Save, then run a test connection.
Nango retrieves the instance_url from Salesforce automatically and stores it in the connection config, so you do not need to supply it. If you use the Nango Proxy, the correct API base URL is applied for you.
Token settings worth changing
One setting on the Salesforce side is worth knowing about even though it is not required to connect. Under the app's Policies, then OAuth Policies, then App Authorization, the Refresh Token Policy controls how long a connection survives. Nango recommends setting it to "Refresh token is valid until revoked" for long lived access.
Leave it on a shorter expiry and your syncs will keep dying at an interval nobody can explain, because the refresh token quietly expired rather than anything in your code breaking.
Troubleshooting
redirect_uri_mismatch. By some distance the most common failure, and the error text is not specific enough to help. It means the callback URL on the Salesforce side differs from the one Nango actually sends: a trailing slash, http instead of https, or a callback copied from a different Nango environment. Copy and paste, never retype.
invalid_client_id. A genuinely strange one, and worth knowing before it costs you an afternoon. Nango's troubleshooting notes that this error can be caused by the developer user's password containing special characters. If the client ID looks correct and it still fails, that is the thing to check.
Scopes decided twice. Teams pick full access to unblock a demo, ship it, then find a customer's security review will not approve it. Narrowing scopes afterwards means a fresh consent from every connected user. Pick the preset you intend to ship with before the first real customer connects.
Frequently Asked Questions
Does Nango work with Salesforce sandboxes as well as production?
Yes. Nango treats sandbox and production as separate integrations, because they are different hosts with different credentials. Create a separate external client app for each, or add both callback URLs to one app and keep the environments straight by name.
Do I really need two Salesforce orgs?
Only for packaged distribution, and only on the manual path. The restriction is that a single org cannot both have Dev Hub enabled and hold a registered namespace, so packaging requires one of each. If you are only connecting your own org, one account is enough.
Is an external client app the same as a connected app?
They do the same job for OAuth and both give you a consumer key and secret. The connected app is the older org-level model; the external client app is the newer metadata-based replacement. Salesforce turned off connected app creation in the UI by default on new orgs in Winter '26, and from Spring '26 re-enabling it needs Salesforce Support.
Where do I find the Salesforce client ID and secret?
On the manual path: the app's Settings tab, OAuth Settings section, then Consumer Key and Secret, after verifying your identity. On the short path they are shown as soon as the app is created. Either way, the consumer key is the client ID.
Which scopes does Nango need for Salesforce?
At minimum api plus refresh_token or offline_access. api lets Nango read and write records, and the refresh scope keeps the connection alive without sending users back through consent. Add the identity scopes if people will sign in with their Salesforce account.
Do I need the Salesforce CLI?
Only for packaged distribution. Local distribution is a web form. If you provision the app rather than building it by hand, you do not need the CLI at all, because the managed package link comes with the app.
Can I change the redirect URL after the app is created?
Yes, and you should expect to. Redirect URLs are editable afterwards, so you can add a production callback alongside a staging one rather than provisioning a second app.
What is the managed package link for?
It is the install link for the packaged version of the app, for when a customer needs it in their own Salesforce org rather than connecting to yours. If you are only connecting your own org to Nango, you can ignore it.
Related Articles
- What is an external client app in Salesforce
- Connected app vs external client app compared
- Salesforce external client app OAuth flows
- What is a managed package in Salesforce
Sources
- Nango Docs, Salesforce API OAuth app setup: external client apps only, local and packaged distribution, environment setup, scopes, refresh token policy, invalid client ID troubleshooting. 2/ Nango Docs, API authorization configuration and callback URLs. 3/ Salesforce Help, External Client Apps. 4/ Appnigma, Salesforce External Client App product, flow and scope presets verified 18 August 2026.
