> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce Setup: External Client App and OAuth

> Connect Salesforce with an External Client App. Set up OAuth callbacks, consumer credentials, permission sets, and agent access to your org.

Connect Salesforce to OneCLI with an External Client App, then give an agent access.

> [!WARNING]
>
> Keep Consumer Secrets out of chat, screenshots, and source code. Salesforce API access can include writes. Limit both the Salesforce user’s permissions and the agent’s access.

## Before you start

* Use a Salesforce administrator account to configure the app and permission sets. The user connecting OneCLI needs API access and the appropriate CRM permissions.
* Use your Salesforce **My Domain** host, such as `your-company.my.salesforce.com` or `your-company.sandbox.my.salesforce.com`.

> [!NOTE]
>
> Screenshots use example names and domains. Red numbers match the actions below each image. Some screens show saved settings, so click **Edit** before making changes.

## Set up your connection

Salesforce uses your own External Client App on OneCLI Cloud and self-hosted alike, so these steps are the same everywhere.

**1. Start in OneCLI**

Open **Connections → Apps → Salesforce → Connect** in the workspace or organization you want to connect.

![OneCLI Salesforce setup popup with the setup guide link, Redirect URI copy button, and empty credential fields.](https://mintcdn.com/chartdbinc/y-cRtdYnhnBqPivg/images/integrations/salesforce/00-onecli-setup.png?fit=max\&auto=format\&n=y-cRtdYnhnBqPivg\&q=85\&s=f0a51b180640e3bb44e8cfe3385a2eef)

Start with the Salesforce setup popup in OneCLI.

[View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/00-onecli-setup.png)

* **1.** The **Salesforce setup guide** link opens this guide in a new tab.
* **2.** Copy your **Redirect URI**. You’ll paste it into Salesforce next. Do not use the example URL shown here.
* **3.** Leave this popup open. After the Salesforce setup, return to enter the **Consumer Key**, **Consumer Secret**, and **Environment**, then **Save & Connect**.

**2. Create the app**

In Salesforce **Setup**, search for **External Client App Manager** in Quick Find.

![Open the External Client App Manager.](https://mintcdn.com/chartdbinc/Mnt4_Jddiutw73Ni/images/integrations/salesforce/01-app-manager.png?fit=max\&auto=format\&n=Mnt4_Jddiutw73Ni\&q=85\&s=94d2be0ebcf520424349d4fc8bda11b0)

Open the External Client App Manager.

[View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/01-app-manager.png)

* **1.** Click **New External Client App**.

Enter these settings:

| Field | Value |
| - | - |
| External Client App Name | `OneCLI` |
| API Name | Keep the generated value |
| Contact Email | Your administrator’s email |
| Distribution State | **Local** |

Expand **API (Enable OAuth Settings)** and check **Enable OAuth**. Leave unrelated features off. **Local** limits distribution to this Salesforce organization, not to localhost.

**3. Set the callback and scopes**

![Register your callback and select only the three required scopes.](https://mintcdn.com/chartdbinc/Mnt4_Jddiutw73Ni/images/integrations/salesforce/02-oauth-scopes.png?fit=max\&auto=format\&n=Mnt4_Jddiutw73Ni\&q=85\&s=fffcc9fe17dd5d7cd4e99b346cac0269)

Register your callback and select only the three required scopes.

[View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/02-oauth-scopes.png)

* **1.** Paste the exact **Redirect URI** from OneCLI into **Callback URL**.
* **2.** Add only these scopes: **api**, **refresh\_token / offline\_access**, and **openid**.

Use your own HTTPS domain or active tunnel, not the example domain. URLs must match exactly. For multiple environments, add one actual callback per line. Copy organization-level callbacks from OneCLI rather than assuming the workspace path.

Leave **Introspect all Tokens** and **Configure ID token** off.

**4. Keep security protections enabled**

![Keep client-secret requirements, PKCE, and refresh-token rotation enabled.](https://mintcdn.com/chartdbinc/Mnt4_Jddiutw73Ni/images/integrations/salesforce/03-oauth-security.png?fit=max\&auto=format\&n=Mnt4_Jddiutw73Ni\&q=85\&s=0e3f7f64a1ed7ac40de0146093597fb5)

Keep client-secret requirements, PKCE, and refresh-token rotation enabled.

[View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/03-oauth-security.png)

* **1.** Enable both **Require secret** options.
* **2.** Keep **PKCE** enabled. OneCLI uses S256.
* **3.** Keep **Refresh Token Rotation** enabled. Salesforce may require these settings.

Leave all optional **Flow Enablement** choices off, including **Authorization Code and Credentials Flow**. That option is not needed for OneCLI’s standard web-server OAuth flow.

Click **Create** or **Save** and confirm the app is **Enabled**.

**5. Copy consumer credentials**

Open **OneCLI → Settings → OAuth Settings** in the External Client App Manager.

![Open consumer details without exposing credentials in this guide.](https://mintcdn.com/chartdbinc/Mnt4_Jddiutw73Ni/images/integrations/salesforce/02-oauth-scopes.png?fit=max\&auto=format\&n=Mnt4_Jddiutw73Ni\&q=85\&s=fffcc9fe17dd5d7cd4e99b346cac0269)

Open consumer details without exposing credentials in this guide.

[View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/02-oauth-scopes.png)

* **1.** Click **Consumer Key and Secret** and complete any identity verification.

Copy **Consumer Key** (client ID) and **Consumer Secret** into the matching OneCLI fields privately. Set **Environment** to `production` or `sandbox`, according to the Salesforce organization, not where OneCLI is hosted.

**6. Connect and test in OneCLI**

1. In OneCLI, confirm the credentials, **Environment**, and **Redirect URI**, then click **Save & Connect**.
2. Sign in as the connecting Salesforce user. Confirm OneCLI shows **Connected** with the expected account and instance.
3. Grant the connection to the intended agent through **Agent access** or the agent’s **Apps** settings.
4. For a read-only first test, allow the needed read tools, set **Write / delete** to **Never**, and save. The `api` scope is not read-only.
5. Ask the agent: “Use my connected Salesforce account to make a fresh request listing available CRM objects. Do not create, update, or delete records.”

> [!TIP]
>
> **Setup complete.** Salesforce is connected and your agent can use it. The section below is optional hardening.

## Restrict who can authorize the app (optional)

> [accordion] Optional: allow only admin-approved users
>
> By default, Salesforce lets any user in your organization authorize the app (**All users may self-authorize**). The three steps below restrict authorization to administrator-approved users only. Recommended for production organizations.
>
> **1. Create a permission set**
>
> In Salesforce **Setup**, search for **Permission Sets** and click **New**.
>
> ![Create a dedicated permission set without adding unrelated privileges.](https://mintcdn.com/chartdbinc/Mnt4_Jddiutw73Ni/images/integrations/salesforce/06-create-permission-set.png?fit=max\&auto=format\&n=Mnt4_Jddiutw73Ni\&q=85\&s=49e72f88aa9bfa7ba5f82200bcc7a952)
>
> Create a dedicated permission set without adding unrelated privileges.
>
> [View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/06-create-permission-set.png)
>
> * **1.** Set **Label** to `OneCLI App Access`. Keep the generated API name.
> * **2.** Leave **Session Activation Required** unchecked.
> * **3.** Set **License** to **--None--**.
> * **4.** Click **Save**.
>
> Do not add administrator or broad data permissions. This permission set authorizes app access. Existing user permissions determine accessible CRM data.
>
> **2. Link the permission set**
>
> Return to **External Client App Manager → OneCLI → Policies → Edit**.
>
> ![Require administrator-approved users.](https://mintcdn.com/chartdbinc/Mnt4_Jddiutw73Ni/images/integrations/salesforce/05-permitted-users.png?fit=max\&auto=format\&n=Mnt4_Jddiutw73Ni\&q=85\&s=f4e55c5bf3c6c19c754945b947ad5026)
>
> Require administrator-approved users.
>
> [View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/05-permitted-users.png)
>
> * **1.** Under **OAuth Policies**, set **Permitted Users** to **Admin approved users are pre-authorized**.
>
> ![Link OneCLI App Access to the External Client App.](https://mintcdn.com/chartdbinc/Mnt4_Jddiutw73Ni/images/integrations/salesforce/04-permission-set-link.png?fit=max\&auto=format\&n=Mnt4_Jddiutw73Ni\&q=85\&s=e1e382246fedb92885bfa5fd9a1f9815)
>
> Link OneCLI App Access to the External Client App.
>
> [View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/04-permission-set-link.png)
>
> * **1.** Under **App Policies**, select **OneCLI App Access** on the left and click the right arrow.
> * **2.** Confirm it appears in **Selected Permission Sets**, then save.
>
> Keep **Start Page** = **None** and **Selected Profiles** empty. Leave OAuth Start URL, custom scopes, and Apex Plugin Class blank.
>
> Keep the required refresh-token idle expiration, typically **30 days**, and your organization’s IP restrictions. Do not choose **Immediately expire refresh token** or relax security to bypass an error.
>
> **3. Assign the connecting user**
>
> Open **Setup → Permission Sets → OneCLI App Access → Manage Assignments**.
>
> ![Assign the permission set to the user who will authorize OneCLI.](https://mintcdn.com/chartdbinc/Mnt4_Jddiutw73Ni/images/integrations/salesforce/07-manage-assignments.png?fit=max\&auto=format\&n=Mnt4_Jddiutw73Ni\&q=85\&s=d2cf3e7152d590cf7ea382be1a62a9a0)
>
> Assign the permission set to the user who will authorize OneCLI.
>
> [View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/07-manage-assignments.png)
>
> * **1.** Click **Add Assignment**, select the exact user who will sign in to Salesforce from OneCLI, then click **Next**.
> * **2.** After assigning, confirm that user appears here. The example’s administrator profile is not required.
>
> ![Choose an assignment expiration that follows your organization’s policy.](https://mintcdn.com/chartdbinc/Mnt4_Jddiutw73Ni/images/integrations/salesforce/08-assignment-expiration.png?fit=max\&auto=format\&n=Mnt4_Jddiutw73Ni\&q=85\&s=17b618572040ef73d10100b12a561fbb)
>
> Choose an assignment expiration that follows your organization’s policy.
>
> [View full-size screenshot](https://onecli.sh/docs/images/integrations/salesforce/08-assignment-expiration.png)
>
> * **1.** Choose **No expiration date** only if ongoing access is approved.
> * **2.** Otherwise, set the expiration required by your organization.
> * **3.** Verify the user and expiration, then click **Assign → Done**.
>
> Both links are required once **Admin approved users are pre-authorized** is set: the app must include the permission set, and the connecting user must have it assigned. A user without the assignment gets **OAUTH\_APP\_ACCESS\_DENIED** when authorizing, including users who connected successfully before the policy change. Assignment expiration is separate from refresh-token idle expiration.

## Troubleshooting

> [accordion] User is not admin approved / OAUTH\_APP\_ACCESS\_DENIED
>
> Check the app’s selected permission set, the exact login user’s assignment, its expiration, and the Salesforce organization. This error appears only when **Permitted Users** is set to **Admin approved users are pre-authorized** (the optional hardening steps) and the connecting user lacks the permission set. Retry authorization after assigning it.

> [accordion] Redirect URI mismatch
>
> Copy the URI again from OneCLI. Check HTTPS, host, path, trailing slash, workspace versus organization scope, and your tunnel’s destination.

> [accordion] Invalid client or exposed secret
>
> Use credentials from the same enabled app and the correct Salesforce environment. If a secret was exposed, rotate it in Salesforce, update OneCLI privately, and reconnect. Do not reset your Salesforce password.

> [accordion] Expired or revoked refresh token
>
> Reconnect through Salesforce OAuth. Idle expiration or revocation can require fresh authorization.

> [accordion] Connected, but the agent cannot use Salesforce
>
> Grant the connection to that agent and request a fresh test. Operators should check for outdated runners or gateways. Do not paste access tokens into chat or create duplicate custom credentials.

> [accordion] API, IP, or permission error
>
> Check Salesforce API entitlement, the user’s API Enabled and object/field permissions, and the agent’s OneCLI permissions. Have an administrator allow required OneCLI egress IPs if needed. Extra scopes do not fix missing permissions.

## Next steps

* [Grant the connection to an agent](https://onecli.sh/docs/guides/agent-access.md).
* [Add organization-wide rules](https://onecli.sh/docs/guides/rules.md).
* [Understand OAuth app connections](https://onecli.sh/docs/integrations/app-connections.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.