Skip to main content
Connect Salesforce to OneCLI with an External Client App, then give an agent access.
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.
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.

Start with the Salesforce setup popup in OneCLI.

View full-size screenshot
  • 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.

Open the External Client App Manager.

View full-size screenshot
  • 1. Click New External Client App.
Enter these settings: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.

Register your callback and select only the three required scopes.

View full-size screenshot
  • 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.

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

View full-size screenshot
  • 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.

Open consumer details without exposing credentials in this guide.

View full-size screenshot
  • 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.”
Setup complete. Salesforce is connected and your agent can use it. The section below is optional hardening.

​
Restrict who can authorize the app (optional)

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.

Create a dedicated permission set without adding unrelated privileges.

View full-size screenshot
  • 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.

Require administrator-approved users.

View full-size screenshot
  • 1. Under OAuth Policies, set Permitted Users to Admin approved users are pre-authorized.
Link OneCLI App Access to the External Client App.

Link OneCLI App Access to the External Client App.

View full-size screenshot
  • 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.

Assign the permission set to the user who will authorize OneCLI.

View full-size screenshot
  • 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.

Choose an assignment expiration that follows your organization’s policy.

View full-size screenshot
  • 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

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.
Copy the URI again from OneCLI. Check HTTPS, host, path, trailing slash, workspace versus organization scope, and your tunnel’s destination.
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.
Reconnect through Salesforce OAuth. Idle expiration or revocation can require fresh authorization.
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.
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