An External Client App (ECA) is Salesforce's next generation framework for letting an outside application connect to your org over OAuth, and it is the direct replacement for the classic Connected App. As of the Spring '26 release, Salesforce disables the creation of new Connected Apps by default across every org, so an External Client App is now the standard way to set up a new integration. This guide, reviewed for the Spring '26 release, covers what an ECA is, how it differs from a Connected App, and how to create one in a few minutes.
What is an External Client App?
Salesforce defines an External Client App as a "packageable framework to enable a third-party application to integrate with Salesforce using APIs and security protocols." It provides single sign-on and uses the SAML and OAuth protocols to authorize outside applications, exactly like a Connected App did. Salesforce calls it "the new generation of connected apps."
The important difference is under the hood. An ECA splits its configuration into two separate pieces:
- A global OAuth settings file that holds the sensitive parts, the consumer key and consumer secret. This piece is never packaged and should never go into source control.
- A local OAuth settings file that holds the distributable, admin-facing configuration.
That separation is the whole point. It keeps a developer's proprietary credentials cleanly apart from the policies an admin customizes per org, which was the messy part of Connected Apps. An ECA is also built for modern packaging: you choose a distribution state when you create it.
| Distribution state | Meaning |
|---|---|
| Local | Available only in the org where you create it |
| Packaged | Distributed to subscriber orgs through second-generation managed packaging (2GP) |
One practical note on that choice: when a sandbox is cloned or refreshed, only packaged ECAs are copied over. Local ECAs are not, so decide the distribution state up front based on where the app needs to run.
External Client App vs Connected App
Both do the same job, authorize an external system to call Salesforce APIs. The ECA just does it with better security defaults and a cleaner packaging model. Here is the side by side.
| Dimension | Connected App | External Client App |
|---|---|---|
| Metadata model | One file, developer and admin settings combined | Split into separate global (developer) and local (admin) files |
| Access default | Open by default, available to users unless restricted | Secure by default, access granted explicitly by profile or permission set |
| Developer and admin roles | Not separated | Distinct developer and admin roles |
| Packaging | 1GP, limited 2GP | Full 2GP with a Local or Packaged distribution state |
| Username-Password OAuth flow | Supported but not recommended | Blocked, not available |
| Metadata API creation | Restricted | Full Metadata API support |
| Sandbox clone | Always copied | Only packaged apps copied, local apps are not |
Salesforce's own guidance is direct: "We recommend that you use external client apps in all situations and migrate existing local connected apps to local external client apps."
Why the "New Connected App" button is gone
If you went looking for the old button and could not find it, that is expected. In the Spring '26 release (release 260), Salesforce disabled the creation of new Connected Apps by default across both the Setup UI and the Metadata API, with the only exception being apps that arrive through package installation. Existing Connected Apps keep working exactly as before. Only the creation of new ones is blocked. Turning creation back on now requires a request to Salesforce Support, and even then the recommended path for anything new is an External Client App.
How to create an External Client App, step by step
You create an ECA from the same place you used to create a Connected App, the App Manager. The whole flow takes a few minutes.
- Go to Setup, type App Manager in Quick Find, and open App Manager.
- Click New External Client App.
- Fill in the basic information: a Name (the display name), an API Name (it defaults from the name, must start with a letter, and allows only letters, numbers, and underscores), and a Contact Email.
- Set the Distribution State to Local for a single org, or Packaged if you plan to distribute it through a managed package.
- Under the API section, check Enable OAuth.
- Enter a Callback URL, the redirect URI your app uses after login. For a quick test in Postman, use
https://oauth.pstmn.io/v1/callback. - Move the OAuth scopes your integration needs from Available to Selected.
- Click Create.
Once the app exists, finish the setup in two more steps. First, open the app's OAuth settings and enable the specific flow your integration uses, which is covered in the next section. Second, retrieve the Consumer Key and Consumer Secret from the app's OAuth settings. Those two values are what your external system exchanges for an access token, so store them somewhere secure and never commit them to a repository.
Choose the right OAuth flow
An ECA supports the modern OAuth flows and blocks the insecure ones. Pick the flow that matches how your integration authenticates.
| OAuth flow | Best for |
|---|---|
| Authorization Code with PKCE | User facing web and mobile apps |
| Client Credentials | Server to server backend integrations with no user present |
| JWT Bearer | Certificate based, machine to machine, high security |
| Device | Input constrained devices such as a CLI or IoT hardware |
| Refresh Token | Keeping a session alive after the first login |
For a backend service that syncs data with no human in the loop, use the Client Credentials flow. As Salesforce puts it, you use it "to share information between two applications without any input from a user." One requirement to know before you start: the Client Credentials flow needs a designated execution user, the "Run As" integration user whose permissions the app runs under. Assign that user a permission set with the right access, because an ECA grants nothing by default.
Create an ECA with metadata or Salesforce DX
Developers can skip the UI and create an ECA as source. The External Client App is a metadata component with the .eca suffix, stored in an externalClientApps folder, and available from API version 59.0 (Winter '24) onward. The External Client App Manager UI itself reached general availability in Summer '24.
An ECA is not a single file. You deploy a small set of metadata types together:
| Metadata type | Holds |
|---|---|
| ExternalClientApplication | The header file for the app configuration |
| ExtlClntAppOauthSettings | The OAuth settings, packageable |
| ExtlClntAppGlobalOauthSettings | The consumer key and secret, not packageable, managed on the Dev Hub |
| ExtlClntAppOauthConfigurablePolicies | The admin OAuth policies |
Deploy them like any other source, for example with sf project deploy start --manifest package.xml --target-org yourOrg. The one prerequisite is that the org has opted in to External Client Apps, a setting you enable once before the first deploy.Common gotchas to plan for
- Access is secure by default. Unlike a Connected App, an ECA gives users no access until you grant it through a profile or permission set. If your integration returns an authorization error right after setup, this is usually why.
- Guard the consumer key and secret. They live in the global OAuth settings. Salesforce warns that "any person or app that has access to your external client app's consumer key and consumer secret can get an access token," so treat them like passwords and rotate them if exposed.
- Client Credentials needs a Run As user. No integration user, no token. Assign the permission set before you test.
- Distribution state is a one time design decision. Local apps do not clone into sandboxes, so choose Packaged if the app has to travel between orgs.
Migrating an existing Connected App
You do not have to rebuild from scratch. In App Manager, open a local Connected App and choose Migrate to External Client App. Salesforce walks the settings across into a new ECA. After the migration the original Connected App becomes read only, and your integration keeps running on the new framework. Because Spring '26 blocks new Connected App creation, migrating the ones you already have is the clean way to stay current without a support request.
Setting up an External Client App correctly, with the right OAuth flow, the right scopes, and a properly permissioned integration user, is the foundation of every reliable Salesforce integration. It is also the kind of plumbing that quietly breaks a project when it is rushed. If you would rather have the integration built and secured for you, a done for you Salesforce partner like Appnigma AI handles the ECA, the OAuth setup, and the connection end to end.
Frequently Asked Questions
What is an External Client App in Salesforce?
An External Client App (ECA) is a packageable framework that lets a third-party application integrate with Salesforce over OAuth and SAML. Salesforce calls it the new generation of Connected Apps, built with better security defaults and a cleaner packaging model.
What is the difference between a Connected App and an External Client App?
A Connected App combines developer and admin settings in one file and is open by default. An External Client App splits those settings into separate global and local files, is secure by default, supports full second-generation packaging, and blocks the insecure Username-Password OAuth flow.
Can you still create Connected Apps in Salesforce?
Not by default. As of the Spring '26 release, Salesforce disabled the creation of new Connected Apps across the UI and Metadata API, except through package installation. Existing Connected Apps still work, and re-enabling creation requires a request to Salesforce Support.
How do I create an External Client App?
Go to Setup, open App Manager, and click New External Client App. Enter a name, API name, and contact email, set the distribution state, enable OAuth, add a callback URL and scopes, then click Create. Afterward, enable your OAuth flow and copy the consumer key and secret.
Which OAuth flow should I use for a server-to-server integration?
Use the Client Credentials flow. It authenticates two applications with no user present and runs under a designated integration user. Assign that user a permission set with the access your integration needs, since an ECA grants nothing by default.
How do I migrate a Connected App to an External Client App?
In App Manager, open the local Connected App and select Migrate to External Client App. Salesforce moves the settings into a new ECA and marks the original as read only, so your integration keeps working on the newer framework.
Sources
- External Client Apps overview, Salesforce Help
- Comparison of Connected Apps and External Client Apps, Salesforce Help
- External Client Apps and Connected Apps recommendation, Salesforce Help
- Create a Local External Client App, Salesforce Help
- Configure the Client Credentials Flow for External Client Apps, Salesforce Help
- Migrate Connected Apps to External Client Apps, Salesforce Help
- Create an External Client App in Your Org, Salesforce DX Developer Guide
- ExternalClientApplication metadata type, Metadata API Guide
