Log in

Salesforce

Connect Salesforce so agents can query and manage records, and run your flows — plus org JWT credentials for Data Sync.

The Salesforce connector plugs your workspace's agents into your Salesforce org: they can run SOQL/SOSL queries, read and write records, describe objects, and invoke autolaunched flows and Apex actions. A separate organization credential (JWT Bearer) is the substrate for Data Sync pipelines — it exposes no agent tools.

Before You Start

  • Agents connect through each member's own Salesforce account (OAuth), so agents see exactly what that member can see.
  • A Salesforce admin registers a Connected App for your org and pastes its consumer key and secret into Headways. Salesforce has no self-service app registration.
  • Org credentials are not agent-forwardable: the org connection is reserved for Data Sync pipelines and appears in no agent capability manifest.

Personal (user) connection

Each member signs in with their own Salesforce account.

1. Create a Connected App

In Salesforce, go to Setup → App Manager → New Connected App and enable OAuth settings.

2. Add the callback URL

Paste the Redirect URI shown on the connector page (in Headways) into the Connected App's callback URL.

3. Select OAuth scopes

Add api, refresh_token, and offline_access, and enable Require secret for web server flow.

4. Enter the values in Headways

On the Salesforce connector page, paste the consumer key (client ID) and consumer secret, then save. Members choose production or sandbox at connect time — production signs in at login.salesforce.com, sandbox at test.salesforce.com.

Organization credentials (JWT Bearer, Data Sync)

For headless, org-wide pipelines. This credential is validated with a first token mint when saved.

1. Create a Connected App for JWT

In Salesforce, go to Setup → App Manager → New Connected App. Enable Use digital signatures and Enable JWT Bearer Flow.

2. Generate a keypair and upload the certificate

Generate an RSA keypair (for example with openssl). Upload the public certificate to the Connected App and keep the private key. The certificate CN only matters as a shortcut: Headways uses it as the integration username when it is email-shaped (e.g. CN=integration@acme.com). Otherwise the CN can be anything — enter the Salesforce username in step 4.

3. Pre-authorize the integration user

On the Connected App's Manage page, choose Admin approved users are pre-authorized and add the integration user. Note its exact username — you enter it in step 4. That user's permissions bound what a pipeline can read.

4. Enter the values in Headways

Paste the consumer key, select the login host (production or sandbox), enter the integration username (the exact Salesforce username of the pre-authorized user), then paste the private key and certificate. Headways runs a validating token mint on save and tracks the certificate's expiry — renew it before it lapses to avoid a relink.

What the Agent Can Do

Agents read freely; anything that writes or runs a business process lands in your Outbox for approval.

  • soql_query — run a SOQL query and return matching records. No approval. Scope: api.
  • soql_continue — fetch the next page of a query from a prior nextRecordsUrl. No approval.
  • sosl_search — full-text search across records. No approval.

Read records

  • record_get — read one record by object and id, optionally projecting fields. No approval.
  • describe_object — describe an object's fields and metadata. No approval.
  • list_objects — list the org's objects and their capabilities. No approval.

Write records

  • record_create — create a record. Requires approval.
  • record_update — update fields on a record (partial). Requires approval.
  • record_delete — delete a record. Requires approval.

Run processes

  • flow_invoke — invoke an autolaunched Flow by API name with its declared inputs. Requires approval.
  • apex_list — list the Apex invocable actions in the org. This is an admin-only discovery endpoint; if access is denied, contact your Salesforce admin or invoke a known action by class name. No approval.
  • apex_invoke — invoke an Apex action by class name. Requires approval.

Security Notes

  • All agent traffic flows through the egress gateway, which allows only *.salesforce.com and the REST data paths, and injects the token there — the agent never holds a credential.
  • Salesforce enforces each member's object, field, and sharing rules; permission and API-limit errors are relayed verbatim.
  • Refresh tokens, private keys, and certificates are stored encrypted server-side and never returned to the browser.
  • Refresh-token rotation (single-use Connected Apps) is persisted automatically; a revoked credential flips the connection to needs reconnect.