---
title: "SalesForce (External Client Apps) on Multiple Organizations"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/salesforce_external_client_apps_on_multiple_organizations-icon.png
date: 2026-04-15T18:48:00.000Z
tag: Guides
description: "This guide will walk you through the required steps to support using a Salesforce External Client App (ECA) across multiple organizations. When an ECA is..."
url: "https://unified.to/blog/salesforce_external_client_apps_on_multiple_organizations"
---

# SalesForce (External Client Apps) on Multiple Organizations
------
_April 15, 2026_

This guide will walk you through the required steps to support using a Salesforce External Client App (ECA) across multiple organizations. When an ECA is created in Salesforce, it can only connect to users within the organization that created it. To allow the ECA to be used across multiple organizations, you must complete the required setup steps before it can connect to users outside the original organization. The customer's Salesforce admin does not need to give anyone their Salesforce credentials, they can run the second set of steps below.


> ⚠️ This setup resolves the error 'Cross-org [OAuth](/embeddedauth) flows are not supported for this external client app'. That error usually means the External Client App was created in your SourceOrg but has not yet been installed/deployed/approved in the customer's TargetOrg.


### Terminology


| Term                    | Meaning                                                                 |
| ----------------------- | ----------------------------------------------------------------------- |
| SourceOrg               | The Salesforce org where the External Client App was created            |
| TargetOrg               | The customer's Salesforce org where users are trying to connect         |
| APP_API_NAME            | API Name of the External Client App                                     |
| OAUTH_SETTINGS_API_NAME | Metadata name of the OAuth settings attached to the External Client App |
1. The first thing you need to do is create an ECA within Salesforce. If you have already done this proceed to step 2, otherwise check out our [how to guide](https://unified.to/blog/how_to_register_a_salesforce_developer_app_and_get_oauth_2_credentials).

![Screenshot_2026-04-29_at_11.06.56_AM.png](https://s3.us-east-2.amazonaws.com/unified-article-images/salesforce_external_client_apps_on_multiple_organizations-0.png)

1. [Install SalesForce CLI](https://developer.salesforce.com/tools/salesforcecli)
2. Generate a SalesForce project

    ```shell
    sf project generate --name unified-sf
    ```

3. Navigate into project

    ```shell
    cd unified-sf
    ```

4. Login to your Source organization, this is the organization where you have created the External client app

    ```shell
    sf org login web --alias SourceOrg
    ```

5. Retrieve the app metadata (Replace APP_API_NAME with your app name, which can be found at Setup → External Client Apps → open your app → settings → basic information → API Name

    ```shell
    sf project retrieve start --metadata ExternalClientApplication:APP_API_NAME --target-org SourceOrg
    sf project retrieve start --metadata ExtlClntAppOauthSettings --target-org SourceOrg
    ```


    > ℹ️ After retrieval, look in `force-app/main/default/extlClntAppOauthSettings/` for a file like `salesforce-test-app_oauth.extlClntAppOauthSettings-meta.xml`. The part before `.extlClntAppOauthSettings-meta.xml` is your `OAUTH_SETTINGS_API_NAME`. It is usually NOT the same as `APP_API_NAME` (it often ends with `_oauth`), so confirm it from the retrieved file name instead of guessing.

6. Create a zip of the project folder to give to the customer who wants to install your app.

    ```shell
    zip -r ../my_project.zip . --exclude "*/.git/*" --exclude "*/.sfdx/*"
    ```


Customer Steps (Customer Salesforce admin)

1. Customer opens the project folder

```javascript
cd my_project
```

1. [Install SalesForce CLI](https://developer.salesforce.com/tools/salesforcecli)
2. Customer admin logs into the TargetOrg

```javascript
sf org login web --alias TargetOrg
```

1. The customer will need to make some changes within their Salesforce to deploy the app. In the SalesForce Dev Hub > Settings > Setup > Dev Hub, enable both 'Enable Unlocked Packages and Second-Generation Managed Packages' and 'Enable Dev Hub'

![Screenshot_2026-04-15_at_3.37.45_PM.png](https://s3.us-east-2.amazonaws.com/unified-article-images/salesforce_external_client_apps_on_multiple_organizations-1.png)


![Screenshot_2026-04-15_at_1.44.39_PM.png](https://s3.us-east-2.amazonaws.com/unified-article-images/salesforce_external_client_apps_on_multiple_organizations-2.png)

1. Customer deploys the ECA app

```javascript
sf project deploy start --metadata ExternalClientApplication:APP_API_NAME --target-org TargetOrg
sf project deploy start --metadata ExtlClntAppOauthSettings:APP_API_NAME_oauth --target-org TargetOrg
```


> ℹ️ Replace `APP_API_NAME_oauth` above with the real `OAUTH_SETTINGS_API_NAME` from the retrieved file name (it may differ from `APP_API_NAME`).


Alternative: deploy both metadata types together:


```shell
sf project deploy start --metadata ExternalClientApplication --metadata ExtlClntAppOauthSettings --target-org TargetOrg
```

1. The customer can then verify that the app has been added to their organization by visiting Setup → External Client Apps → external client app manager where they should see your app installed.

![Screenshot_2026-04-29_at_11.06.47_AM.png](https://s3.us-east-2.amazonaws.com/unified-article-images/salesforce_external_client_apps_on_multiple_organizations-3.png)

1. Configure and approve access in the TargetOrg. The admin should review and configure:
    - Permitted users
    - Profiles / permission sets
    - OAuth policies
    - Refresh token policy
    - IP restrictions, if applicable
    - Admin-approved users, if the org requires admin approval
2. The customer can now create a connection to your app

Once the app is deployed and access is granted, the end user can retry the normal Salesforce connection flow through Unified and the cross-org OAuth error will be resolved.


## Long-term application-distribution recommendation


For repeated customer onboarding, the preferred long-term approach is to package the External Client App as a Salesforce package and share a package install link with customer Salesforce admins, instead of asking each admin to manually run metadata deployment commands.

1. You create the External Client App once in SourceOrg.
2. You package the app and OAuth settings.
3. You share the package install link with customer admins.
4. The customer Salesforce admin installs the package into TargetOrg.
5. The customer Salesforce admin approves/configures access.
6. End users connect normally through OAuth.