> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/integrations/crm-and-revops/salesforce-integration/connecting-salesforce-with-a-connected-app.md).

# Connecting Salesforce with a Connected App

PeakCommerce connects to your Salesforce org through a **Connected App** using the OAuth 2.0 **client-credentials flow** — a server-to-server connection with no interactive login, no browser redirect, and no refresh tokens. You create the Connected App in Salesforce, then enter three values into PeakCommerce: the **Login URL**, the **Consumer Key**, and the **Consumer Secret**. From then on, PeakCommerce mints a short-lived access token on each call and writes to Salesforce through the REST and SOAP APIs.

This is the connection layer that powers the Salesforce commerce actions — creating and converting leads, and creating accounts and opportunities during signup, checkout, and CSR-initiated orders. For what those actions do end to end, see [Salesforce Sales Cloud Integration](/integrations/crm-and-revops/salesforce-integration/salesforce-sales-cloud-integration.md).

## Which Salesforce user do the writes run as?

**This is the most important thing to get right, and it is configured in Salesforce, not in PeakCommerce.** The client-credentials flow does not act "on behalf of" whichever users have authorized the app. Instead, every Connected App that enables this flow must designate a single **"Run As" user**. Every access token PeakCommerce receives — and therefore every lead, account, and opportunity it creates — executes as that one user. That user's profile and permission sets define what PeakCommerce can see and write, and records PeakCommerce creates are owned by that user by default.

So there is no per-account assignment inside PeakCommerce, and it does not matter how many people can log in through the app for other purposes. The account that PeakCommerce's writes are attributed to is entirely determined by the **Run As user** on the Connected App.

### "Record owner" means two different things — check which one you need <a href="#record-owner-two-places" id="record-owner-two-places"></a>

Record ownership in PeakCommerce is set in **two unrelated places**, and they are changed in different systems. Before changing anything, work out which one you are looking at:

| What you want to change                                                                                   | Where it lives                                                | How to change it                                                                                                                                                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The **default** owner of everything PeakCommerce writes — leads, accounts, opportunities                  | The Connected App's **Run As** user, **in Salesforce**        | Salesforce **Setup → App Manager**, edit the Connected App's client-credentials settings (below)                                                                                                                                                                                                   |
| The owner set **explicitly on one operation** — e.g. an `OwnerId` field mapping on a `create_lead` action | A **field mapping on a commerce action**, **in PeakCommerce** | **Content → Journeys →&#x20;*****your journey*****&#x20;→ Edit → Steps →** expand the step **→ Edit action**, then edit the field — see [Commerce Actions](https://gitlab.com/peak-hercules/peak-help-docs/-/tree/main/product/journeys-and-pages/journey-steps/commerce-actions.md#field-mapping) |

An explicit `OwnerId` mapping **overrides** the Run As default for that operation. So if leads are landing on the wrong owner, or Salesforce rejects a write with **`INVALID_CROSS_REFERENCE_KEY` — "invalid cross reference id"**, check the action's field mapping first: a hardcoded Salesforce user id that was copied from a **sandbox** org does not exist in production, and no amount of changing the Run As user will fix it.

There is no "Run As" setting inside PeakCommerce. If you are looking for one in **Settings → Integrations**, you are in the wrong place — that screen holds the connection (Login URL, Consumer Key, Consumer Secret), not the identity.

**Recommendation:** create a **dedicated integration user** in Salesforce and set it as the Run As user, rather than reusing a real person's account. Salesforce provides free **Salesforce Integration** user licenses for exactly this purpose. Give it a minimal permission set (create/read on Lead, Account, Opportunity, and Contact, plus permission to convert leads) so the connection follows least privilege and its actions are clearly attributable in your audit trail.

## Setting it up

### 1. Create the Connected App in Salesforce

In your Salesforce org, go to **Setup → App Manager → New Connected App** (or **New External Client App** — see [the migration note below](#connected-apps-are-being-replaced-by-external-client-apps)).

* Enable **OAuth Settings**.
* Enable the **Client Credentials Flow**.
* Under the flow's settings, select the **Run As** user (your dedicated integration user).
* Save, then open **Manage Consumer Details** to copy the **Consumer Key** and **Consumer Secret**.

> Salesforce may take several minutes to activate a newly created or edited Connected App before the client-credentials token endpoint will issue tokens.

### 2. Enter the credentials in PeakCommerce

Go to **Integrations → CRM**, add or edit the Salesforce integration, and fill in:

| Field               | What to enter                                                                                                                                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Environment**     | Choose **Sandbox** or **Production**. This pre-fills the Login URL.                                                                                                                                                   |
| **Login URL**       | Your org's login host — `https://login.salesforce.com` (production), `https://test.salesforce.com` (sandbox), or your `https://<your-domain>.my.salesforce.com` My Domain URL. Must be HTTPS and a Salesforce domain. |
| **Consumer Key**    | The Connected App's Consumer Key.                                                                                                                                                                                     |
| **Consumer Secret** | The Connected App's Consumer Secret. When editing, leave the key and secret fields empty to keep the stored values unchanged.                                                                                         |

Use **Test Connection** to confirm the credentials before saving. A successful test means PeakCommerce obtained an access token from your org with the client-credentials flow.

## What PeakCommerce does with the connection

Once connected, PeakCommerce performs these operations as the Run As user:

* **Create Lead** — when a visitor enters their details during a signup journey.
* **Convert Lead** (with or without an Opportunity) — when that visitor completes checkout, the lead is converted into an Account (and Contact).
* **Create Account** — when a CSR or customer creates an account in-app.
* **Create Opportunity** — attached to the relevant account when the journey calls for it.

All of these calls flow through PeakCommerce's outbound governance and are recorded in **API Call Stats**, so a rejected or failed Salesforce call stays visible for diagnosis rather than being hidden.

## Connected Apps are being replaced by External Client Apps

Salesforce is phasing out Connected Apps in favor of **External Client Apps (ECAs)**:

* As of the **Spring '26** release, Salesforce **disables the creation of new Connected Apps** by default. Existing Connected Apps keep working for now, but Salesforce is expected to announce end-of-support for them.
* A separate **security mandate takes effect on May 11, 2026**, requiring hardened OAuth settings on both Connected Apps and External Client Apps.
* Salesforce provides a native migration path: **Setup → App Manager →** select your Connected App **→ Migrate to External Client App**.

**Good news: this requires no changes in PeakCommerce.** External Client Apps fully support the client-credentials flow, and the connection details are the same — the same login/token endpoint, the same Consumer Key and Consumer Secret, and the same **Run As** user concept.

When you migrate a Connected App to an ECA (or create a new integration as an ECA):

1. Confirm the **Client Credentials Flow** is enabled on the ECA and a **Run As** user is set.
2. If the migration issues a new Consumer Key or Secret, re-enter them in **Integrations → CRM** in PeakCommerce and re-test the connection.

> External Client Apps do not support the older username-password OAuth flow. PeakCommerce never used that flow, so there is nothing to change on that account.

## Related

* [Salesforce Sales Cloud Integration](/integrations/crm-and-revops/salesforce-integration/salesforce-sales-cloud-integration.md)
* [What Salesforce apps does PeakCommerce natively integrate with?](/integrations/crm-and-revops/salesforce-integration/what-salesforce-apps-does-peakcommerce-natively-integrate-with.md)
* [Agentforce](/integrations/crm-and-revops/salesforce-integration/agentforce.md)
* [CRM & RevOps](/integrations/crm-and-revops/crm-and-revops.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.peakcommerce.com/integrations/crm-and-revops/salesforce-integration/connecting-salesforce-with-a-connected-app.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.