Connect Salesforce to OneCLI with an External Client App. Set up OAuth callbacks, consumer credentials, permission sets, assignment expiration, and agent access.
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.
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.
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
12
Register your callback and select only the three required scopes.
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
123
Keep client-secret requirements, PKCE, and refresh-token rotation enabled.
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.
1
Open consumer details without exposing credentials in this guide.
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
In OneCLI, confirm the credentials, Environment, and Redirect URI, then click Save & Connect.
Sign in as the connecting Salesforce user. Confirm OneCLI shows Connected with the expected account and instance.
Grant the connection to the intended agent through Agent access or the agent’s Apps settings.
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.
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.
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.
1234
Create a dedicated permission set without adding unrelated privileges.
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.
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.
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.
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.
Redirect URI mismatch
Copy the URI again from OneCLI. Check HTTPS, host, path, trailing slash, workspace versus organization scope, and your tunnel’s destination.
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.
Expired or revoked refresh token
Reconnect through Salesforce OAuth. Idle expiration or revocation can require fresh authorization.
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.
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.
