Connecting Athean with Salesforce

Athean connects to Salesforce as one Salesforce user that your Salesforce administrator chooses, called the integration user in this guide. Everything Athean reads from or writes to Salesforce goes through that user, including CRM sync, Salesforce live fields, Salesforce filters, contacts exported to Salesforce, and automations that read or update Salesforce records. Athean can see and change only what the integration user's permissions allow, and Salesforce shows Athean's changes as made by that user.

Athean signs in as the integration user with a certificate. It doesn't use the user's password, a browser sign-in, or a Consumer Secret.

Connecting takes two parts:

1. A Salesforce administrator prepares Salesforce with one of two options:
   • Option 1, the Athean managed package (recommended): install Athean's connected app from a package. It's the fastest setup.
   • Option 2, your own External Client App: create and manage Athean's app in your Salesforce org yourself.
2. You email Athean the connection details, and Athean's team finishes and checks the connection. There is no Org settings page for connecting Salesforce.

Salesforce restricts creating new connected apps as of its Spring '26 release and recommends External Client Apps for new integrations, so Option 2 uses one. Installing the managed package isn't affected, and connected apps that already exist keep working.

Each Athean organization connects to one Salesforce org, either production or a sandbox. Do every step in that org, signed in as a System Administrator or another administrator who can install or configure apps and assign permission sets.

Choose the Salesforce user Athean connects as. A user dedicated to Athean is best, but it can be an existing user. The user must be active, have the API Enabled permission, and have a Salesforce license that includes API access to the data Athean needs. It doesn't need the System Administrator profile.

Before you set up access, agree with Athean which objects and fields it reads, creates, or edits, including custom fields. Then give the integration user only that access, through its profile or permission sets:

• Object and field permissions: Read on every object and field Athean reads, and Create and Edit on every object and field it writes to. Athean can't save a record the user can't create or edit.
• Record visibility: sharing access to the records Athean works with. Athean can't read records or fields the user can't see.

What Athean writes depends on the features you use: contacts, leads, and accounts that CRM sync creates or updates, activity that CRM sync writes (such as Task or Event records), fields people edit as Salesforce live fields, and fields that automations update. See CRM sync and troubleshooting for the activity your organization's mappings write.

Authorizing the user for Athean's app, in either option, only lets Athean sign in as the user. The user's profile, permission sets, field permissions, and sharing access decide what Athean can read or change.

1. While signed in to your production Salesforce org, open the Athean managed package install page and install the package. For a sandbox, email support@athean.com for the sandbox install link.
2. In Setup, open Permission Sets, select New, and create a permission set named Athean Permission Set 2. The package also installs a permission set, but you need this separate one for the next steps.
3. In Athean Permission Set 2, open Assigned Connected Apps, select Edit, add Athean, and save.
4. Select Manage Assignments, then Add Assignment, and assign the permission set to the integration user.
5. In Setup, open App Manager. In the Athean row (App Type Connected (Managed)), open the menu at the end of the row and select Manage. You don't create an app for Option 1, so don't use New External Client App.
6. Select Edit Policies. Under OAuth Policies, set Permitted Users to Admin approved users are pre-authorized, then select Save.

To check the setup:

• App Manager lists Athean.
• On Athean's Manage page, Permitted Users shows Admin approved users are pre-authorized, and Permission Sets lists Athean Permission Set 2.
• In Athean Permission Set 2, Manage Assignments lists the integration user, and Assigned Connected Apps lists Athean.
• The integration user is active, has API Enabled, and has the object, field, and record access you agreed with Athean.

Then send Athean your connection details.

Before you start:

• Email support@athean.com for Athean's public certificate. You upload it in step 5.
• Decide how the app authorizes the integration user: with a permission set assigned to the user, or with the user's profile if that profile is only for integrations. To use a permission set, create it and assign it to the integration user first.

1. In Setup, open App Manager and select New External Client App.
2. Enter Athean as the External Client App Name and API Name, and your email address as the Contact Email. Set Distribution State to Local.
3. Under API (Enable OAuth Settings), select Enable OAuth and enter http://localhost as the Callback URL. Salesforce requires a callback URL, but Athean doesn't use it.
4. Under OAuth Scopes, add only Manage user data via APIs (api) to the selected scopes. Don't add Full access (full) or Manage user data via Web browsers (web) unless Athean's team asks you to. Athean doesn't use refresh tokens, so it doesn't need Perform requests at any time (refresh_token, offline_access).
5. Under Flow Enablement, select Enable JWT Bearer Flow, select Upload Files, and upload Athean's public certificate. Leave the other flows off. Enable Client Credentials Flow is a different sign-in method, and its Consumer Secret and run-as user settings don't apply to Athean.
6. Select Create.
7. In Setup, open External Client App Manager, open Athean, select the Policies tab, and select Edit.
8. Under OAuth Policies, set Permitted Users to Admin approved users are pre-authorized.
9. Under App Policies, select the integration user's permission set or profile, then select Save.
10. Select the Settings tab, expand OAuth Settings, and select Consumer Key and Secret. Confirm your identity when Salesforce asks, then copy the Consumer Key.

Manage the app in External Client App Manager. It isn't listed under Manage Connected Apps or in a permission set's Assigned Connected Apps, so the integration user is authorized through the app's App Policies instead.

If you created the app without the certificate, open Athean in External Client App Manager, edit its Settings, expand OAuth Settings, select Enable JWT Bearer Flow, and upload the certificate there.

To check the setup:

• Enable OAuth and Enable JWT Bearer Flow are selected, and Athean's certificate is uploaded.
• Permitted Users shows Admin approved users are pre-authorized.
• App Policies includes the integration user's permission set or profile.
• The integration user is active, has API Enabled, and has the object, field, and record access you agreed with Athean.

Then send Athean your connection details.

Email support@athean.com with:

• Which option you used: the Athean managed package or your own External Client App.
• Your Salesforce My Domain URL, shown in Setup → My Domain (for example, https://acme.my.salesforce.com), and whether the org is production or a sandbox.
• The integration user's exact Salesforce Username, copied from the user's record. It can differ from the user's email address.
• For Option 2, the Consumer Key. Option 1 doesn't need one.
• The objects and fields you agreed Athean can read or write, including custom fields.

Don't send the integration user's password or the Consumer Secret. Athean doesn't use them.

Athean's team finishes the connection, then checks that Athean can sign in and read the agreed objects and fields. If Athean will write to Salesforce, agree with the team on a test record to write and how to clean it up. The connection is ready when these checks succeed, not when Athean appears in Salesforce. Athean's team tells you when it's ready.

After Salesforce is connected, an organization administrator can set up:

• CRM sync mappings: what Athean writes to Salesforce. See CRM sync and troubleshooting.
• Salesforce live fields: the Salesforce fields people see and edit on records. See Layout configuration.
• Salesforce filters: reusable filters on Salesforce data for Discover and Signals. See Salesforce filters.

• The integration user loses access: if the user is deactivated, loses the API Enabled permission, or loses the permission set or profile that authorizes it (Athean Permission Set 2 for Option 1, or the one in the app's App Policies for Option 2), Athean can't read from or write to Salesforce until access is restored.
• Switching integration users: give the new user the same access and the same authorizing permission set or profile, then email the new username to support@athean.com.
• Password changes: changing the integration user's password doesn't affect the connection.
• Athean can't sign in to Salesforce: check the exact username, the environment (production or sandbox), the Permitted Users policy, and that the user has the authorizing permission set or profile. For Option 2, also check the Consumer Key and the uploaded certificate. Email support@athean.com the error and which option you used. Don't send passwords.
• Records or fields are missing in Athean: check the integration user's object permissions, field access, and record visibility in Salesforce.
• Athean can't save to Salesforce: check the attempt in CRM sync and troubleshooting. The integration user needs Create and Edit access on the object, and your Salesforce validation rules and required fields still apply.
• A connected app you created earlier: if you connected Athean through a connected app you created instead of an External Client App, it keeps working. Keep its configuration unless you're moving to an External Client App with Athean's help.