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

# External Client App and Connection Setup

> External Client App specification and connection requirements for the WeGive Salesforce Nonprofit Cloud integration

Before you can connect WeGive to your Salesforce Nonprofit Cloud (NPC) org, you need to create an **External Client App (ECA)** in Salesforce with the proper OAuth settings and permissions.

<Note>
  **No managed package for NPC.** NPC does not require a managed package install. WeGive syncs against the standard NPC objects (`GiftTransaction`, `GiftCommitment`, `GiftDesignation`, `GiftSoftCredit`, and related) using the standard REST API (Bulk API 2.0 is used only for `CampaignMember` batch push operations — see [Integration Nuances](/external/onboarding/npc/integration-nuances)). You create the External Client App yourself using the steps below.
</Note>

## Prerequisites

Make sure your Salesforce org and user meet these requirements before you begin:

* **Nonprofit Cloud is enabled and configured** on the org (production or sandbox).
* **Person Accounts are enabled.** These are required for NPC individual supporters. WeGive discovers your Person Account record type ID automatically at connect time; without Person Accounts the donor sync will not work.
* **A dedicated integration user** with:
  * The **Fundraising Access** permission set license
  * The **Fundraising User** permission set
* **System Administrator access** to create the External Client App and to authorize OAuth.

<Tip>
  Use a dedicated integration user rather than a personal admin account. This keeps the connection stable if an admin changes roles or leaves, and it isolates the integration's activity in your Salesforce logs.
</Tip>

## Step 1: Confirm the integration is available on your account

Salesforce Nonprofit Cloud is a separate integration from Salesforce NPSP and is enabled per WeGive account. If **Salesforce Nonprofit Cloud** does not appear under **Settings > Integrations**, ask your WeGive contact to enable it before continuing.

## Step 2: Create the External Client App

### Create the ECA

1. Log in to Salesforce and go to **Setup**.
2. In the Quick Find box, search for **External Client App Manager** and select it.
3. Click **New External Client App**.
4. Fill in the following:
   * **Name:** `WeGive`
   * **Contact Email:** `support@wegive.com`
   * **Distribution State:** Local
   * **Enable OAuth:** Yes
   * **Callback URL:** `https://api.wegive.com/api/oauth/npc/callback`

### Set OAuth scopes

* **Manage user data via APIs (`api`)**
* **Perform requests at any time (`refresh_token`, `offline_access`)**

### Configure flow and security settings

Under **Flow Enablement**:

* **Enable Authorization Code and Credentials Flow:** Yes
* All other flows: No

Under **Security**:

* **Require Secret for Web Server Flow:** Yes
* **Require Secret for Refresh Token Flow:** Yes

Click **Create**.

### Edit ECA policies

1. From the ECA detail page, click **Edit Policies**.
2. Set **IP Relaxation** to **Relax IP restrictions**.
3. Save.

### Copy your credentials

On the ECA **Settings** page, expand **OAuth Settings** and open **Consumer Key and Secret**. You will need both when connecting WeGive in Step 3.

### Add a Remote Site Setting

1. In Salesforce Setup, go to **Security > Remote Site Settings**.
2. Click **New Remote Site**.
3. Enter:
   * **Remote Site Name:** `wegive_api`
   * **Remote Site URL:** `https://api.wegive.com`
4. Save.

<Warning>
  **Allow up to 10 minutes for activation.** The External Client App may take up to 10 minutes to become active after creation. If you see an authorization error when connecting WeGive, wait a few minutes and try again.
</Warning>

## Step 3: Connect WeGive to Salesforce

<Steps>
  <Step title="Sign out of Salesforce">
    Sign out of every Salesforce session in your browser, or use a private window. The authorization step signs in as whoever is currently logged in, and WeGive is bound to that user until you disconnect.
  </Step>

  <Step title="Open the integration settings">
    In the WeGive dashboard, go to **Settings > Integrations > Salesforce Nonprofit Cloud** and open the **Connection** tab.
  </Step>

  <Step title="Enter the org and credentials">
    In **Salesforce Login URL**, enter your org's My Domain URL (for example `https://yourorg.my.salesforce.com/`). Sandbox and Production have different My Domain URLs. Paste the **Consumer Key** and **Consumer Secret** from Step 2, then click **Save**.
  </Step>

  <Step title="Authorize">
    Click **Test Connection**. Salesforce prompts you to sign in; sign in as the **integration user** and approve access. Back in WeGive, the header changes to **OAuth connected**.
  </Step>

  <Step title="Enable the integration">
    Turn on **Enable Integration**. WeGive discovers your record type IDs, supported API versions, and picklist values, and seeds the pull filters. Review [Configuration Options](/external/onboarding/npc/configuration-options) and the [Data Mapping Overview](/external/onboarding/npc/data-mapping/overview) before turning on individual sync toggles.
  </Step>
</Steps>

Authorization is per org. A Test dashboard authorizes against a Sandbox and a Live dashboard against Production; switching orgs means re-running the authorization. Use the **Sync** button on the Connection tab to run a pull immediately at any time.

**Enable Integration is locked until a successful connection test passes** — the toggle stays disabled with a "Run a successful connection test before enabling Salesforce NPC synchronization" hint until **Test Connection** succeeds at least once, matching the NPSP screen's behavior.

## Salesforce licensing notes

The NPC objects (`GiftTransaction`, `GiftCommitment`, `GiftDesignation`, and related) require the **Fundraising Access** permission set license. That license grants the integration user the ability to create and modify records on these objects. Pair it with the **Fundraising User** permission set on the integration user.

## Common connection failures

| Symptom | Cause |
| - | - |
| Authorization error right after creating the app | The External Client App is not yet active; activation can take up to 10 minutes. |
| Insufficient access when the integration writes records | The integration user lacks the Fundraising Access permission set license, the Fundraising User permission set, or object access listed under [Setup Requirements](/external/onboarding/npc/setup-requirements#integration-user). |
| Supporters do not sync | Person Accounts are not enabled, or were enabled after WeGive connected. WeGive discovers the Person Account record type at connect time; re-run the authorization after enabling them. |
| Connection reaches the wrong org | The Salesforce Login URL points at the wrong My Domain. Sandbox and Production have different My Domain URLs, and a Test dashboard can only authorize against a Sandbox. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.