Skip to main content
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.
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).

​
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:
    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 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. 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.
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.