What Is an External Client App (ECA) in Salesforce, and How to Create One (2026)

A Salesforce ECA, or External Client App, is the framework Salesforce now uses to let an outside application connect to an org over OAuth, and it replaces the classic Connected App. Since the Spring '26 release, Salesforce disables the creation of new Connected Apps by default in every org, so an External Client App is the standard way to set up a new integration. Salesforce recommends ECAs "in all situations."

Last reviewed: September 17, 2026, against Salesforce Help, the Metadata API Developer Guide and the Spring '26 and Winter '27 release notes listed under Sources.

What is an External Client App in Salesforce?

An External Client App is what Salesforce Help calls a packageable framework "to enable a third-party application to integrate with Salesforce using APIs and security protocols." External Client Apps provide single sign-on (SSO) and use the SAML (Security Assertion Markup Language) and OAuth protocols to authorize outside applications, the same job a Connected App did. Salesforce describes ECAs as "the new generation of connected apps".

The design difference is how an ECA separates its configuration. Salesforce splits the OAuth settings into two files and keeps admin policies apart from both:

• Global OAuth settings hold the OAuth consumer details, the consumer key and consumer secret. Because they are sensitive, this file can never be packaged and must not be added to source control.
• Local OAuth settings hold the rest of the OAuth configuration. Developers control these settings, and they are packaged and distributed to subscriber orgs.
• Policies are what a subscriber org admin manages: who may use the app, token lifetimes and session rules. Policies are never packaged, so each org sets its own.

That split keeps a developer's credentials apart from the choices each customer's admin makes, which the single-file Connected App model mixed together.

External Client App distribution state: Local or Packaged

Every ECA has a distribution state that decides where it can run. The table shows the two values you choose from when creating the app.

Salesforce names second-generation managed packaging (2GP) as the distribution route for packageable ECAs and also supports first-generation (1GP) managed packages. The distribution state matters for sandboxes: when a sandbox is cloned or refreshed, only packaged External Client Apps are copied. Local ECAs are not, so decide the state up front based on where the app needs to run. For how packaging itself works, see the Salesforce managed package guide to 1GP and 2GP.

Salesforce ECA vs Connected App

A Salesforce ECA and a Connected App both authorize an external system to call Salesforce APIs. The ECA does it with a metadata model built for packaging and separate developer and admin roles. The table summarizes Salesforce's feature comparison.

Salesforce's 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." The same page adds that some features are still only available through Connected Apps, so check the comparison before migrating an app that relies on something like user provisioning.

For the full side by side, including a migration plan for an existing app, see Connected App vs External Client App in Salesforce.

Why the "New Connected App" button is gone

The New Connected App option is missing because of a Spring '26 change. The release note Creation of New Connected Apps Is Disabled by Default (release 260) turned off the ability to create new Connected Apps in all Salesforce orgs and removed the "Allow creation of connected apps" preference. Existing Connected Apps keep working normally. Salesforce's knowledge article on the change adds that creation through APIs, including the Metadata API, is blocked the same way as the UI, with package installation as the exception.

To turn creation back on, you contact Salesforce Customer Support, and the knowledge article notes that Support won't be able to do this in future releases. The Winter '27 release update Migrate All Connected Apps to External Client Apps, listed in the Winter '27 release updates, states that in Summer '27 Salesforce ends support for Connected Apps. Connected Apps will keep working after that, but Salesforce will no longer fix bugs in them or provide support.

How to create an External Client App, step by step

You create an External Client App in App Manager, the same Setup page that used to hold the New Connected App button. The steps follow Salesforce's Create a Local External Client App instructions.

1. From Setup, enter App Manager in Quick Find and select App Manager.
2. Click New External Client App.
3. Enter a Name (the display name) and an API Name. The API name must start with a letter, use only letters, numbers and underscores, be unique, and contain no spaces, no trailing underscore and no two consecutive underscores.
4. Enter a Contact Email.
5. Set the Distribution State to Local for a single org, or Packaged if you plan to distribute the app in a managed package.
6. In the API section, select Enable OAuth.
7. Enter a Callback URL, the redirect URI your app uses after login. It must use HTTPS or a custom URI scheme. For a quick test in Postman, use https://oauth.pstmn.io/v1/callback.
8. Select the OAuth scopes your integration needs.
9. Click Create.

Two tasks remain once the app exists. First, enable the OAuth flow your integration uses, covered in the next section. Second, retrieve the credentials: in External Client App Manager, click Edit Settings, open OAuth Settings, and click Consumer Key and Secret. Salesforce sometimes asks you to verify your identity with a code sent by email first. Your external system exchanges these two values for an access token, so store them in a secrets manager and never commit them to a repository.

Appnigma also provisions an External Client App for you: you give it a name, redirect URLs and a scope preset, and it returns the client ID (Salesforce's consumer key), the secret and a managed package install link, without a partner application or Salesforce setup screens.

Which OAuth flow should a Salesforce ECA use?

A Salesforce ECA supports the modern OAuth 2.0 flows, and the Username-Password flow is not available. The table lists the flows Salesforce documents under Set Up OAuth Flows for External Client Apps and what each is for.

For a backend service that syncs data with no human in the loop, use the Client Credentials flow. Salesforce describes it as the way "to share information between two applications without any input from a user." The flow needs an execution user, the integration user whose permissions every request runs under; Connected Apps labeled the same field "Run As." You enable the flow in the app's settings and then enter the execution user's username in its policies.

The Client Credentials flow does not issue refresh tokens, and requests must go to your My Domain URL rather than login.salesforce.com. The Salesforce integration user guide covers the license and permission set that user needs. Each flow's setup is detailed in Salesforce External Client App OAuth.

Device flow is restricted to local External Client Apps

The Winter '27 release update Restrict the OAuth 2.0 Device Flow to Local External Client Apps limits the Device flow to local ECAs with a localhost callback URL. The update became available in late Summer '26 and is enforced on November 30, 2026. After enforcement, the Device flow no longer works for Connected Apps, packaged External Client Apps, or local External Client Apps without a localhost callback URL. If a CLI or device integration depends on that flow, move it to a local ECA with a localhost callback before that date.

Create an ECA with metadata or Salesforce DX

Developers can create an External Client App as source instead of in the UI. The ExternalClientApplication metadata type uses the .eca suffix, is stored in an externalClientApps folder, and is available in API version 59.0 and later. The External Client App Manager screen arrived later, in the Summer '24 release.

An ECA is deployed as a set of metadata components rather than one file. The Metadata API Developer Guide lists 12 ECA types; the four below make up a typical OAuth integration.

The other eight types cover canvas, mobile, push, notification and SAML settings and their policies. Deploy the set like any other source, for example:

sf project deploy start --manifest package.xml --target-org yourOrg

Two org settings govern metadata access. The Metadata API reference says access to the ExternalClientApplication type requires the Opt in to External Client Apps setting in Setup. Reading or deploying the consumer secret through metadata also requires Allow Access to OAuth Consumer Secrets via Metadata API, plus the View External Client Apps Consumer Secrets in Metadata user permission for the developer. For authorizing the Salesforce CLI itself, Salesforce's DX guide walks through creating an External Client App in your org.

How to manage an External Client App after you create one

External Client App Manager in Setup is where an ECA is governed after creation. The table maps the four settings teams most often need to where each one lives.

The Permitted Users choice has a consequence worth planning for. Salesforce warns that if you switch from "All Users can self-authorize" to "Admin approved users are pre-authorized", anyone using the app loses access unless a permission specifically authorizes them for that ECA. Users with the "Use Any API Client" permission can still reach an admin-approved-only app.

Two habits help. Grant the narrowest scope set the integration actually uses, because an enterprise admin reviewing the app sees every requested scope. And check the OAuth Usage page on a schedule rather than during an incident, so you know which users and tokens a revocation would affect before you make one.

Common External Client App setup problems

Four settings are worth checking first when a new ECA does not work.

• Permitted Users excludes the caller. When Permitted Users is set to admin approved users, a user without an assigned profile or permission set gets an authorization error. Assign access before testing. The Salesforce OAuth errors reference maps the specific error messages.
• The consumer key and secret leaked. 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." Treat them like passwords and rotate them on a schedule and immediately if exposed. ECAs support staged key and secret rotation through a Connect REST API endpoint.
• Client Credentials has no execution user. Without an execution user, the flow cannot issue a token. Set the user in the app's policies and give it a permission set first.
• The distribution state was chosen for the wrong environment. Local apps do not copy into cloned or refreshed sandboxes, so choose Packaged if the app has to move between orgs.

If the integration calls out from Salesforce rather than into it, the credential setup lives elsewhere: see Named Credentials and External Credentials in Salesforce.

How to migrate a Connected App to an External Client App

Salesforce provides a built-in migration for existing Connected Apps. In Setup, open App Manager and view the Connected App; if it meets every eligibility requirement, a Migrate to External Client App button appears. According to Salesforce's migration guide:

• Migration preserves the consumer key and secret, so existing integrations keep working, and refresh tokens remain valid.
• The original Connected App is saved as a read-only version. Don't delete it, because both apps share the same consumer.
• The migrated External Client App is local to your org.
• An app is not eligible if it uses user provisioning, a custom Apex handler, Canvas, dynamic client registration, Triple DES SAML encryption, or (for apps that aren't internal) standard notification subscriptions.
• Connected Apps used for single sign-on can't be migrated, and migration runs only in the Setup UI, not through an API or the CLI.
• The migration tool can't detect Username-Password flow usage, and that flow stops working after migration, so check your integrations first.

For Connected Apps installed through a managed package, Salesforce's knowledge article says the vendor that owns the package handles the migration.

Frequently Asked Questions

What is a Salesforce ECA?

A Salesforce ECA (External Client App) 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 and recommends it for all new integrations.

What is the difference between a Connected App and an External Client App?

A Connected App combines developer and admin settings in one file. An External Client App separates global OAuth settings, local OAuth settings and admin policies, supports full Metadata API and 2GP packaging, and does not offer the Username-Password OAuth flow.

Can you still create Connected Apps in Salesforce?

Not by default. Since Spring '26, Salesforce disables new Connected App creation in the UI and through APIs, except by package installation. Existing Connected Apps still work, and re-enabling creation requires a request to Salesforce Customer 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, and click Create. Then enable your OAuth flow and copy the consumer key and secret from the OAuth settings.

What is the External Client App distribution state?

The distribution state is either Local, meaning the app runs only in the org where it was created, or Packaged, meaning it is distributed to subscriber orgs in a managed package. Only packaged External Client Apps are copied when a sandbox is cloned or refreshed.

What is the Run As user for an External Client App?

For External Client Apps, Salesforce calls it the execution user: the integration user whose permissions the Client Credentials flow runs under. You enter the execution user's username in the app's policies after enabling the flow.

How do I manage an External Client App after creating it?

Use External Client App Manager in Setup. Change OAuth scopes under Edit Settings, set the refresh token policy and Permitted Users under Policies, and use the External Client Apps OAuth Usage page to see authorized users and revoke tokens.

How do I migrate a Connected App to an External Client App?

In App Manager, view the eligible Connected App and click Migrate to External Client App. Salesforce keeps the consumer key, secret and refresh tokens, creates a local External Client App, and saves the original Connected App as a read-only version you should not delete.

Related Articles

• Connected App vs External Client App in Salesforce
• Salesforce External Client App OAuth flows
• The Salesforce integration user: license, setup and limits
• Salesforce OAuth errors: a troubleshooting reference

Sources

• External Client Apps overview, Salesforce Help: definition, settings split, distribution state, sandbox copy rule.
• Comparison of Connected Apps and External Client Apps, Salesforce Help: feature comparison table.
• External Client Apps and Connected Apps, Salesforce Help: the recommendation to use External Client Apps.
• Creation of New Connected Apps Is Disabled by Default, Spring '26 release notes
• Connected App creation changes, Salesforce knowledge article 005228017
• Winter '27 release updates, including Migrate All Connected Apps to External Client Apps
• Restrict the OAuth 2.0 Device Flow to Local External Client Apps, Winter '27 release notes
• Create a Local External Client App, Salesforce Help
• Configure the Client Credentials Flow for External Client Apps, Salesforce Help
• Migrate a Connected App to an External Client App, Salesforce Help
• Create an External Client App in Your Org, Salesforce DX Developer Guide
• ExternalClientApplication metadata type, Metadata API Developer Guide
• ExtlClntAppGlobalOauthSettings metadata type, Metadata API Developer Guide