> ## 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 configuration, NPSP trigger handler exclusions, and connecting WeGive to Salesforce NPSP

WeGive connects to Salesforce using OAuth 2.0 through an **External Client App (ECA)** in your Salesforce org. This page covers the ECA configuration, the recommended NPSP trigger handler exclusions, and completing the connection in the WeGive dashboard.

## Prerequisites

* WeGive4SF is installed and the **WeGive Admin** permission set is assigned to the integration user (see [Installing the WeGive Salesforce Managed Package](/external/onboarding/salesforce-npsp/install-setup/package-install))
* You are logged in as a **System Administrator**
* You know the integration user's Salesforce username

## 1. Create the External Client App

In **Setup**, search for **External Client App Manager** and click **New External Client App**.

| Field | Value |
| - | - |
| Name | `WeGive` |
| Contact Email | `support@wegive.com` |
| Distribution State | Local |
| Enable OAuth | Yes |
| Callback URL | `https://api.wegive.com/api/oauth/salesforce/callback` |
| OAuth Scopes | Manage user data via APIs (`api`); Perform requests at any time (`refresh_token`, `offline_access`) |
| Flow Enablement | **Authorization Code and Credentials Flow**: Yes. All other flows: No. |
| Require Secret for Web Server Flow | Yes |
| Require Secret for Refresh Token Flow | Yes |

Use the same callback URL for Production and Sandbox orgs.

<Warning>
  A new External Client App can take up to 10 minutes to activate. An `OAUTH_APPROVAL_ERROR_GENERIC` during that window resolves on retry.
</Warning>

## 2. Relax IP restrictions

Open the app, click **Edit Policies**, set **IP Relaxation** to **Relax IP restrictions**, and save. WeGive does not connect from a fixed IP range.

## 3. Add a Remote Site Setting

In **Setup > Security > Remote Site Settings**, click **New Remote Site** and enter:

| Field | Value |
| - | - |
| Remote Site Name | `wegive_api` |
| Remote Site URL | `https://api.wegive.com` |

## 4. Copy the credentials

On the ECA detail page, open **Settings > OAuth Settings** and copy the **Consumer Key** and **Consumer Secret**. You will enter both in WeGive.

## NPSP trigger handler exclusions

NPSP uses trigger handlers (its Table-Driven Trigger Management framework) to run automation whenever records change: recalculating allocations, validating payments, keeping allocations and payments in step. That automation is designed for records people enter by hand. WeGive writes complete, already-consistent records: the Opportunity, its Payment, and its GAU Allocations arrive together with amounts that already balance. When NPSP re-processes those records, two things go wrong. First, it can create duplicate or conflicting Allocation and Payment records, which then sync back to WeGive as new data. Second, NPSP's processing runs inside the same transaction as WeGive's write, so a large sync can push against Apex governor limits and fail partway through.

WeGive's recommendation is to exclude the integration user from the handlers below. Excluding by username means NPSP automation still runs normally for every other user in the org; only records written by WeGive bypass it. Each handler has a **Usernames to Exclude** field for exactly this purpose.

To apply the exclusions, open the **App Launcher**, search for **Trigger Handlers**, open the list, and add the integration user's username to **Usernames to Exclude** on each record below.

| Trigger handler | Object | What it does | Why WeGive recommends excluding it |
| - | - | - | - |
| `ALLO_Allocations_TDTM` | `Allocation__c` | Creates and rebalances GAU Allocations when Opportunities and Recurring Donations change. | WeGive sends allocations that already sum to the gift amount. NPSP re-running can add a default allocation or reject the record as over-allocated. |
| `PMT_Payment_TDTM` | `npe01__OppPayment__c` | Validates Payment records and rolls payment amounts up to the Opportunity. | WeGive sends complete Payment records with amounts that match the Opportunity. Re-validation is redundant and is the most common source of governor limit failures on large syncs. |
| `ALLO_PaymentSync_TDTM` | `Allocation__c` | Keeps Payment-level allocations in step with Opportunity-level allocations. | WeGive manages both levels itself, so this sync can undo or duplicate what WeGive wrote. |

<Warning>
  Do not exclude the user from `PMT_Payment_TDTM` on the **Opportunity** object. That is a separate handler record. WeGive sets `npe01__Do_Not_Automatically_Create_Payment__c = true` on Opportunities it creates, which handles the Opportunity-side behavior without an exclusion.
</Warning>

<Note>
  **When exclusions are optional.** If your org does not use GAU Allocations, the two `Allocation__c` handlers have nothing to act on and can be left alone. If your org relies on NPSP automation that must run on WeGive-created records (for example, a custom trigger handler that depends on NPSP's allocation processing), discuss the trade-off with your WeGive CS contact before excluding. This list may grow as NPSP and WeGive add features; check this page when upgrading either package.
</Note>

<Warning>
  **Open tension, not fully resolved: the exclusion above may suppress allocation propagation the integration relies on.** `syncAllocationsToSF()`'s code comments (`Salesforce.php:4988-4996`) state that WeGive deliberately does NOT push its own allocations onto a recurring-installment Opportunity, because it expects `ALLO_Allocations_TDTM` to auto-propagate the Recurring Donation's GAU Allocations onto that Opportunity on insert — WeGive then "adopts" those propagated records by ID. But the trigger-handler exclusion table above excludes the **integration user** from `ALLO_Allocations_TDTM` globally, with no carve-out for installment Opportunities specifically. If WeGive's integration user is the one inserting the installment Opportunity (its own push), and the exclusion is username-scoped rather than object-subtype-scoped, the exclusion would suppress the very propagation the adoption logic depends on — leaving installment Opportunities under-allocated. This reads as a genuine architectural question, not something resolvable from the WeGive codebase alone (it depends on exactly how NPSP evaluates per-trigger username exclusions relative to who technically initiates the installment Opportunity's creation — NPSP's own scheduled job vs. WeGive's push). Flagging for engineering rather than asserting a resolution either way.
</Warning>

## Connect in WeGive

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

  <Step title="Enter credentials">
    Paste the **Consumer Key** into **Client ID** and the **Consumer Secret** into **Client Secret**. Leave **Legacy Username** and **Legacy Password** blank; they belong to the deprecated username-password flow. Click **Save**.
  </Step>

  <Step title="Authorize">
    Click **Connect with OAuth**. Sign in as the integration user and approve access. The header badge changes from **Not connected** to **OAuth connected**.
  </Step>

  <Step title="Test the connection">
    Click **Test Connection**. WeGive verifies API access and reads your org's record types.
  </Step>

  <Step title="Configure, then enable">
    Complete the **Sync Configuration** and **Mapping Rules** tabs before turning on **Enable Integration**; see the [Dashboard Settings Reference](/external/onboarding/salesforce-npsp/dashboard-settings) and the [Implementation Guide](/external/onboarding/salesforce-npsp/install-setup/implementation-guide).
  </Step>
</Steps>

WeGive detects Sandbox vs Production from the org you authorize. A Test dashboard completes authorization only against a Sandbox, and a Live dashboard only against Production.

## Connection reference

| Item | Value |
| - | - |
| Authorization | OAuth 2.0 Authorization Code flow with refresh token |
| Scopes | `api`, `refresh_token`, `offline_access` |
| Credential storage | WeGive stores the access and refresh tokens encrypted. No Salesforce password is stored. |
| Token refresh | Automatic. If refresh fails repeatedly, the integration is disabled and must be reconnected. |

## Next step

[Data Mapping Overview](/external/onboarding/salesforce-npsp/data-mapping/overview)


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