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

# Connect Salesforce to Athena: Records, SOQL, and Setup

> Salesforce setup covers the connected app, org policies, member sign-in, query and record tools, approval-gated writes, and troubleshooting.

Connect your Salesforce org to Athena so each member can query and search
records, read them, explore objects and fields, and create or update records
as their **own Salesforce user**. Your profiles, permission sets, field-level
security and sharing rules apply unchanged. Athena sees exactly what you can
see in Salesforce, nothing is shared through an integration user, and every
record Athena creates or updates is recorded under your name.

<Info>
  Members can connect once **Athena Intelligence** has registered a Salesforce
  connected app for your workspace. It can be Athena's own app, or one your
  **Salesforce administrator** creates in your org (step 1).
</Info>

## Step 1 — Prepare your org (Salesforce admin)

Depending on your org's security settings:

* **Allow the app.** If your org only allows connected apps it has installed,
  install the app from **Setup → Connected Apps OAuth Usage**, or give members
  the **Approve Uninstalled Connected Apps** permission.
* **Choose who may connect.** Under the app's policies, **All users may
  self-authorize** lets any member with API access connect. **Admin approved
  users are pre-authorized** limits it to the profiles and permission sets you
  assign.
* **Relax IP restrictions.** If your profiles restrict login IP ranges, set the
  app's IP relaxation to **Relax IP restrictions**.
* **API access.** Every member needs the **API Enabled** permission, on an
  edition that includes API access.

### Optional — your own connected app

Create your own app when your org requires one, or when members can sign in
only through your My Domain.

1. In Setup, create a connected app (or an external client app) and enable
   OAuth.
2. Set the **Callback URL**:

   ```text theme={null}
   https://api.athenaintel.com/api/direct-connectors/salesforce_direct/oauth/callback
   ```

   For private or VPC deployments, replace `api.athenaintel.com` with your
   environment's Athena API host. Salesforce requires an exact match.
3. Select the scopes **Manage user data via APIs (api)**, **Perform requests
   at any time (refresh\_token, offline\_access)** and **Access the identity URL
   service (id, profile, email, address, phone)**.
4. Keep **Require secret for Web Server Flow** on and **Require Proof Key for
   Code Exchange (PKCE)** off.
5. Save, then copy the **Consumer Key** and **Consumer Secret**.
6. Send them to Athena Intelligence through a secure channel, with where your
   members sign in: `login.salesforce.com` (production), `test.salesforce.com`
   (sandboxes) or your My Domain, for example `acme.my.salesforce.com`.

## Step 2 — Athena registers the app for your workspace

Athena Intelligence adds a `salesforce_direct` integration for your workspace.
It holds the Consumer Key, the encrypted Consumer Secret and the login host.
Secrets are encrypted at rest and never returned to the browser. Production
and sandboxes sign in at different hosts, so each gets its own integration.
Once one is saved, the **Salesforce** card on the Integrations page is
available to every member. Until then, the card says the integration isn't set
up for the workspace yet.

## Step 3 — Connect your account (each member)

1. Navigate to
   **[Integrations](https://app.athenaintel.com/dashboard/integrations/)** and
   click **Connect Salesforce** on the **Salesforce** card, under **CRM**.
2. Salesforce's sign-in page opens in a popup. Sign in to the org you want to
   connect, then click **Allow**. Athena stores your encrypted tokens and
   confirms the connection with your Salesforce username.
3. If your workspace has more than one integration registered (for example
   production and sandboxes), pick one before connecting. To add another org
   later, click **Connect another Salesforce org**.

## What Athena can do

Once connected, the **Salesforce toolkit** gives agents these tools.

| Tool | What it does | Approval |
| - | - | - |
| List Salesforce Orgs | Lists your connected orgs and the Salesforce user each uses | No |
| List Salesforce Objects | Lists the objects you can query, including custom objects, filtered by name or label | No |
| Describe Salesforce Object | Reads an object's fields, types, required fields, picklist values, lookups and child relationships | No |
| Query Salesforce | Runs a SOQL `SELECT` and pages through large results | No |
| Search Salesforce | Searches accounts, contacts, leads and opportunities (or the objects you name) by keyword | No |
| Get Salesforce Record | Reads one record by ID or by its Salesforce link | No |
| Create Salesforce Record | Creates a record under your name | **Yes**, every time |
| Update Salesforce Record | Changes fields on a record | **Yes**, every time |

A few behaviors to know:

* **Plain-language requests work.** Ask "show my open opportunities closing
  this quarter". Athena builds the SOQL query for you.
* **Several orgs.** With more than one org connected, name the org you mean.
* **Setup objects are never written.** Athena never writes users, profiles,
  permission sets, roles, sharing rows or Apex, whatever your permissions
  allow. There is no delete tool.
* **Reads need no approval.** Read tools run without a prompt in chat and in
  scheduled agent runs that act as you. Write tools are available only in
  chat, where you can approve them. An automation's own identity holds no
  Salesforce connection, so automation steps cannot call Salesforce.

## Use Salesforce from a computer

On a computer with your Salesforce connection attached under **Connected
Catalogs**:

* `SALESFORCE_INSTANCE_URL` holds your org's address.
* `SALESFORCE_API_URL` holds its REST API base,
  `https://<your org>/services/data/v62.0`.
* `athena-catalog-token salesforce_direct` prints a short-lived access token
  for your connection.

```bash theme={null}
curl -H "Authorization: Bearer $(athena-catalog-token salesforce_direct)" \
  "$SALESFORCE_API_URL/query?q=SELECT+Id,Name+FROM+Account+LIMIT+5"
```

With more than one Salesforce org attached, pass the catalog's asset ID
instead of `salesforce_direct`. The computer acts as you, so anyone you share
it with can use your Salesforce access from it: attach your connection only to
a computer you don't share.

## Token lifecycle & troubleshooting

* **Everything is per-user.** Results always reflect *your* Salesforce access,
  and every change is attributed to you.
* **"Reconnect Salesforce."** The refresh token was revoked or expired (the
  app's refresh token policy, a password reset, or an admin revoking the app).
  Reconnecting from the Integrations page fixes it.
* **"redirect\_uri\_mismatch" in the popup.** The app's Callback URL doesn't
  exactly match the one in step 1.
* **"Salesforce API access is off for your user or org."** Your user needs
  the API Enabled permission.
* **"Refused this as you."** Your profile, permission sets or sharing do not
  allow the request. Ask your Salesforce administrator; Athena cannot widen
  your access.
* **API limits.** When your org's API allowance is used up, Athena says so
  instead of retrying.

## Disconnecting

Open the Salesforce connection in Athena and click **Disconnect**. Athena
revokes its access in Salesforce and removes your stored tokens. Other orgs
you connected stay connected.


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