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

# Salesforce

> Connect Circuit to your Salesforce org so agents can query, create, and update records.

The Salesforce integration lets agents read your Salesforce data, run SOQL queries and SOSL searches, and create, update, and delete records on your behalf. It supports both production orgs and sandboxes.

## What you can do

* **Query records**: agents can run SOQL queries across any object your user can access.
* **Search**: agents can run SOSL searches across multiple objects at once.
* **Create, update, and delete records**: agents act with your Salesforce permissions, so you cannot do anything Salesforce itself would not allow you to do.
* **Inspect schema**: agents can describe objects and fields when they need to understand your org's customizations.

## Before you start

* A Salesforce user account in the org you want to connect, with **API Enabled** in your profile or permission set.
* Decide whether you are connecting a **production** org or a **sandbox**. The login URLs are different and selecting the wrong one is the most common cause of failed connections.
* For organizations that restrict OAuth applications, your Salesforce administrator may need to approve Circuit in advance. See [If your org restricts OAuth apps](#if-your-org-restricts-oauth-apps) below.

## Connect Salesforce

<Steps>
  <Step title="Open the Salesforce integration in Circuit">
    In Circuit, open **Settings** > **Integrations** and choose **Salesforce**.
  </Step>

  <Step title="Pick production or sandbox">
    Select **Production** if you sign in to Salesforce at `login.salesforce.com`, or **Sandbox** if you sign in at `test.salesforce.com`. If you are not sure, ask your Salesforce administrator. This is the single most important step.
  </Step>

  <Step title="Sign in to Salesforce">
    Click **Connect Salesforce**. Salesforce opens its sign-in page in a new window. Sign in with the account you want Circuit to act as.
  </Step>

  <Step title="Approve the requested access">
    Salesforce shows a consent screen listing the scopes Circuit requests. Review the scopes (see [What Circuit accesses](#what-circuit-accesses) below) and click **Allow**.
  </Step>

  <Step title="Return to Circuit">
    Salesforce redirects you back to Circuit. The integration status changes to **Connected**. You can now reference Salesforce in any agent's tool configuration.
  </Step>
</Steps>

## What Circuit accesses

Circuit requests two OAuth scopes:

```
api
refresh_token
```

| Scope           | Why Circuit needs it                                                                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api`           | Access and manage data through the Salesforce REST API. This is the scope that lets agents query, create, update, and delete records, scoped to what your Salesforce user is allowed to do. |
| `refresh_token` | Issue a refresh token so Circuit can keep the connection alive in the background. Without this scope, your session would expire and you would need to reconnect every few hours.            |

Circuit uses the **OAuth 2.0 authorization code flow with PKCE**. Your Salesforce password is never seen, stored, or transmitted to Circuit.

<Note>
  Circuit's access to Salesforce data is constrained by your Salesforce user's profile, permission sets, sharing rules, and field-level security. If you cannot see a record in Salesforce, neither can Circuit.
</Note>

## For IT and security teams

The Salesforce integration uses a Circuit-managed Connected App in Salesforce's OAuth platform. Each user authorizes the app individually.

* **Login URLs**: Production goes through `https://login.salesforce.com`. Sandboxes go through `https://test.salesforce.com`.
* **Instance URL**: Circuit detects the user's instance URL (for example, `https://acme.my.salesforce.com`) during the OAuth flow and uses it for all subsequent API calls. If your org migrates between data centers (such as a Hyperforce move), affected users may need to disconnect and reconnect.
* **Restricting Circuit organization-wide**: Salesforce administrators can require admin approval for the Circuit Connected App in **Setup** > **Connected Apps OAuth Usage** > **Manage App Policies**. Set the policy to **Admin approved users are pre-authorized** to restrict who can connect.
* **Audit**: Connected App usage is visible at **Setup** > **Connected Apps OAuth Usage**, and OAuth login events are visible in the **Login History** report.

See [Integration security and admin consent](/it/integration-security) for cross-integration security details.

## Disconnect or rotate access

To disconnect from Circuit's side, open **Settings** > **Integrations** > **Salesforce** in Circuit and click **Disconnect**. Circuit deletes the stored refresh token immediately.

To revoke from Salesforce's side, open your Salesforce profile, go to **Settings** > **Personal Information** > **Connections**, find Circuit, and click **Revoke**. Salesforce administrators can revoke for any user from **Setup** > **Connected Apps OAuth Usage**.

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Invalid login&#x22; or &#x22;authentication failure&#x22; when signing in">
    Almost always caused by choosing the wrong environment. If you sign in to Salesforce at `test.salesforce.com`, you must select **Sandbox** in Circuit. Disconnect and reconnect with the correct environment selected.
  </Accordion>

  <Accordion title="OAuth screen shows 'this app is blocked' or similar">
    Your Salesforce administrator has restricted OAuth apps in your org. Ask them to pre-authorize Circuit in **Setup** > **Connected Apps OAuth Usage**.
  </Accordion>

  <Accordion title="API calls fail with INSUFFICIENT_ACCESS">
    Circuit can only access records your Salesforce user can access. Check your profile, permission sets, sharing rules, and field-level security. The Salesforce error message usually names the object or field.
  </Accordion>

  <Accordion title="The integration shows 'Disconnected' after working previously">
    A refresh token can be invalidated by a password change, an admin revocation, or a long period of inactivity. Disconnect and reconnect to issue a new token.
  </Accordion>

  <Accordion title="&#x22;INVALID_INSTANCE&#x22; errors after a Hyperforce or data center migration">
    Your org's instance URL changed. Disconnect and reconnect so Circuit picks up the new instance URL.
  </Accordion>
</AccordionGroup>

## Reference

* **OAuth flow**: Authorization code with PKCE
* **Scopes requested**: `api`, `refresh_token`
* **Redirect URI**: `https://app.circuit.ai/api/salesforce-oauth`
* **Connected App name shown on consent screen**: Circuit
* **Salesforce's own docs**: [OAuth 2.0 authorization code flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_web_server_flow.htm), [OAuth tokens and scopes](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_tokens_scopes.htm)

## If your org restricts OAuth apps

If your Salesforce administrator has set OAuth Policies to **Admin approved users are pre-authorized**, users will see a "this app is blocked for your org" message. Your admin can resolve this in two ways:

* **Pre-authorize users**: In **Setup** > **Connected Apps OAuth Usage**, find Circuit, then assign profiles or permission sets that are allowed to connect.
* **Switch to "All users may self-authorize"**: Less restrictive, but allows any user with API access to connect.