Skip to main content
The Salesforce integration lets Sofie search, read, and prepare changes for Salesforce records when your organization enables the provider and users connect authorized Salesforce accounts. Use this guide if you administer Salesforce OAuth apps, manage Sofie integrations, or need to coordinate setup with a Salesforce admin.
Salesforce may show Connected Apps or External Client Apps depending on your org and Salesforce release. Use the Salesforce app type that supports API OAuth, authorization code flow, callback URLs, scopes, PKCE, a client ID, and an optional client secret.

​
What Sofie can use

Depending on Salesforce permissions and Sofie configuration, Sofie may help with:
  • Listing available standard and custom Salesforce objects.
  • Describing object fields, picklists, relationships, and supported actions.
  • Searching Salesforce records with keyword search.
  • Querying Salesforce records with read-only SOQL.
  • Reading specific records by object name and record ID.
  • Preparing create, update, upsert, or delete actions for review.
  • Using Salesforce context in chat or workflow handoff.
Salesforce write actions can change external records. Review record names, object API names, fields, values, and timing before approving any update.

​
Before you start

You need:
  • Salesforce administrator access.
  • Permission to create or manage the Salesforce OAuth app.
  • A Salesforce user policy for who can authorize the app.
  • The Sofie domain users open in the browser.
  • Access to Sofie Organization Settings > Integrations.
  • The Integrations feature and Salesforce integration feature enabled in Sofie.
  • A decision about production, sandbox, or My Domain login.
Users who connect Salesforce also need Salesforce API access and permission to the objects and fields they want Sofie to use.

​
Callback URL

Add this callback URL to the Salesforce app:
Use the exact Sofie environment domain. Add staging and production callback URLs separately when needed.

​
Set up the app in Salesforce

Create the Salesforce app before entering values in Sofie.
1

Open app setup in Salesforce

In Salesforce Setup, open App Manager or the app setup area your org uses for OAuth API integrations.
2

Create the app

Create a new Salesforce app for Sofie. Use a clear name such as Sofie Salesforce Integration.
3

Enter contact details

Add the administrator contact email and any required support or policy details for your org.
4

Enable OAuth API settings

Enable the API or OAuth settings for the app. Choose the authorization code or web server flow when Salesforce asks for the OAuth flow type.
5

Add the callback URL

Add https://<your-sofie-domain>/api/integrations/callback/salesforce as a callback URL.
6

Require PKCE when available

Enable Require Proof Key for Code Exchange (PKCE) if your Salesforce app setup offers it. Sofie sends a PKCE code challenge during authorization and a code verifier during token exchange.
7

Add OAuth scopes

Add api and refresh_token or offline_access.
8

Save the app

Save the app and wait for Salesforce to make the app available.
9

Copy OAuth values

Copy the consumer key and, if your policy requires it, the consumer secret.
Salesforce app changes can take several minutes to propagate. If user connection fails immediately after saving, wait and retry before changing the Sofie settings.

​
Configure OAuth scopes

Sofie requests these Salesforce OAuth scopes: Use the least access that supports your approved Sofie workflows. Do not add broad scopes such as full access unless your Salesforce admin approves them for a documented reason.

​
Configure app access in Salesforce

After creating the app, review its Salesforce access policy.
  • Decide whether all approved users can self-authorize or whether access is limited to assigned profiles or permission sets.
  • Confirm connected users have Salesforce API access.
  • Confirm object permissions and field-level security for the records Sofie should use.
  • Review refresh token policy so users do not need to reconnect too often.
  • Review IP, session, SSO, and MFA policies that can affect OAuth sign-in.
Test with a Salesforce user whose permissions match a real target user. A Salesforce administrator can often see records that normal users cannot.

​
Copy Salesforce values

After saving the app, copy these values from Salesforce.
Client Secret is optional for Salesforce in Sofie because Sofie supports PKCE-style authorization. If Salesforce requires a secret for your app policy, enter the consumer secret in Sofie.

​
Choose the auth base URL

Use the URL that matches the Salesforce org users should connect. Use My Domain when your Salesforce org requires it for authentication policy, branding, or SSO. Do not include a trailing slash.

​
Add values in Sofie

In Sofie, go to Organization Settings > Integrations and open Salesforce.
1

Enable Salesforce

Turn on the Salesforce integration.
2

Choose the OAuth app source

Use the organization OAuth app when your Sofie environment should use your Salesforce app instead of default credentials.
3

Enter OAuth values

Enter Client ID, Client Secret if required, and Auth Base URL.
4

Save changes

Save the integration settings. Sofie may require step-up authentication before saving integration secrets.

​
Configure a group override

Use a group override when a specific group should connect to a different Salesforce app, sandbox, production org, or My Domain than the organization default. In Sofie, open the group, configure Salesforce in the group integration settings, and enter:
  • Client ID.
  • Client Secret if required.
  • Auth Base URL when the group should use a specific Salesforce login host.
Group Salesforce credentials override the organization default for members of that group. If the group integration is disabled, members use the organization default.

​
Ask users to connect Salesforce

After the admin setup is saved, users connect their own Salesforce accounts from Sofie Integrations. When a user connects:
  • Sofie redirects the user to the configured Salesforce auth base URL.
  • Salesforce asks the user to authorize the Sofie app.
  • Sofie stores the user connection and Salesforce instance details.
  • Sofie can only use Salesforce records available to that connected user.
If Sofie shows Reconnect Salesforce to enable offline refresh, ask the user to reconnect. The current connection is missing refresh_token or offline_access.

​
Test the connection

1

Connect a representative test user

Use a Salesforce user whose permissions match a real target user.
2

List available objects

Ask Sofie to list Salesforce objects the test user can access.
3

Describe an object

Ask Sofie to describe a known object, such as Account, Case, or a custom object ending in __c.
4

Search or query known records

Ask Sofie to find a known account, contact, opportunity, case, task, event, order, or custom-object record.
5

Read record details

Confirm Sofie can summarize only fields the test user can see.
6

Test write behavior carefully

If write actions are enabled, use a test record and require Sofie to preview all field changes before updating anything.

​
User prompt examples

​
Troubleshooting

Confirm Salesforce is enabled in Sofie, the callback URL matches exactly, the auth base URL points to the right Salesforce org, the app has api and refresh scopes, and the Salesforce app policy allows the user to authorize the app.
Compare the Salesforce callback URL with the Sofie domain users opened in the browser. The scheme, host, and path must match. Add separate callback URLs for staging, production, and any custom Sofie domains.
The connection is missing refresh_token or offline_access. Confirm the Salesforce app includes the refresh scope, then ask users to reconnect.
Confirm the connected Salesforce user can see the record directly in Salesforce. Sofie follows the connected account’s object permissions, field-level security, sharing rules, and API access.
Check Auth Base URL. Use https://test.salesforce.com or your sandbox My Domain for sandbox testing.
Check Salesforce object permissions, field-level security, validation rules, required fields, duplicate rules, assignment rules, and whether the app policy allows the requested action.

​
Official Salesforce references