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 below.
Connect Salesforce
Open the Salesforce integration in Circuit
In Circuit, open Settings > Integrations and choose Salesforce.
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.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.
Approve the requested access
Salesforce shows a consent screen listing the scopes Circuit requests. Review the scopes (see What Circuit accesses below) and click Allow.
What Circuit accesses
Circuit requests two OAuth scopes:| 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’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.
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 throughhttps://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.
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
"Invalid login" or "authentication failure" when signing in
"Invalid login" or "authentication failure" 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.OAuth screen shows 'this app is blocked' or similar
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.
API calls fail with INSUFFICIENT_ACCESS
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.
The integration shows 'Disconnected' after working previously
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.
"INVALID_INSTANCE" errors after a Hyperforce or data center migration
"INVALID_INSTANCE" 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.
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, OAuth tokens and scopes
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.