> ## 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.

# Fixing Virtuous Sync Failures Caused by an Expired API Key

> How to diagnose and resolve mass Virtuous integration sync failures when your API key has expired or been revoked, including how to regenerate the key and bulk-retry locked records

# Fixing Virtuous Sync Failures Caused by an Expired API Key

If your Virtuous integration suddenly stops syncing — with many records showing **Error Execution** in Integration Logs and error messages mentioning "Unauthorized" or an HTTP 401/403 status — the most likely cause is an expired or revoked API key. This guide walks through how to confirm the problem, fix it, and get everything syncing again.

## How to tell this is the problem

Open **Settings → Integrations → Integration Logs** and look for these signs:

* **A burst of Error Execution entries** across many different records (donors, transactions, campaigns), all starting around the same time
* **Error details** (click **Click to view** on any failed log) showing an HTTP **401** or **403** status code, or a message containing "Unauthorized" or "token"
* **The integration disabled itself** — if the Enabled toggle on the Virtuous integration settings page has flipped to off without anyone touching it, WeGive's safety mechanism detected repeated authentication failures and turned the integration off to prevent further errors

The pattern to look for is *everything* failing at once, not just one or two records — a single-record failure is usually a data issue, while a wave of auth-related failures across all record types points to the API key.

## Why this happens

Your Virtuous integration authenticates every API call using the API key you provided during setup. When that key is revoked, rotated, or expires on the Virtuous side, every sync attempt fails. WeGive treats these failures as non-recoverable errors (not temporary glitches), so:

1. **Each failed record gets an error log.** After three consecutive failures on the same record, WeGive stops retrying that record to avoid an endless loop. The record appears in **Integration Logs Ignored**.
2. **After enough auth failures, the integration auto-disables.** This is a safety measure — it prevents WeGive from sending hundreds of doomed requests to Virtuous.

The combination means that even after you fix the key, affected records won't automatically retry — you need to clear the locks manually (step 3 below).

## Step 1: Generate a new API key in Virtuous

1. Log into your **Virtuous CRM** dashboard with an administrator account
2. Go to **Settings → API Keys**
3. Create a new API key (or regenerate the existing one)
   * Give it a clear name, such as "WeGive Integration"
   * Copy the key immediately — Virtuous won't show it again
4. Ensure the key has permissions for Contacts, Gifts, Projects, Segments, and Recurring Gifts (the same permissions your original key had)

## Step 2: Update the key in WeGive and test

1. In **WeGive**, go to **Settings → Integrations → Virtuous**
2. If the integration was auto-disabled (the Enabled toggle is off), turn it back **on**
3. Paste the new API key into the **API Key** field
4. Click **Save**
5. Use the **Test Connection** button to verify the new key works — you should see a success confirmation

<Note>
  When you save a new API key, WeGive automatically re-registers its webhook with Virtuous so real-time sync resumes. You don't need to do anything extra for webhooks.
</Note>

## Step 3: Retry locked records

After confirming the new key works, you need to clear the locks that accumulated during the outage so those records can sync again.

1. Go to **Settings → Integrations → Integration Logs**
2. Use the filters to narrow down:
   * **Status**: Error Execution (or Error, Failed)
   * **Integration Type**: Virtuous
3. Select all the affected logs using the **Select All** checkbox
4. Click **Retry**

WeGive creates a fresh sync attempt for each selected record. With the valid API key in place, these retries should succeed. Monitor the Integration Logs over the next few minutes to confirm records are appearing as **Processed**.

<Tip>
  If you have a very large number of locked records, the retry may take some time to work through the queue. Check back after 15-30 minutes rather than watching it in real time.
</Tip>

## Step 4: Verify everything is healthy

After the retries complete:

* **Check Integration Logs** for any remaining errors — a small number of individual record failures is normal (these are typically data-specific issues unrelated to the key), but you should not see further auth-related errors
* **Spot-check a few records** (open a recent donation or donor and scroll to Integration Logs) to confirm they show **Processed**
* **Confirm the next scheduled pull works** — the next incremental pull from Virtuous should complete without errors

## Preventing this in the future

* **Monitor API key expiration** in Virtuous if your organization has key rotation policies
* **Check Integration Logs periodically** — a quick weekly scan filtered to Error or Error Execution catches problems early, before they lock many records
* **Act quickly on auth failures** — the sooner you replace an expired key, the fewer records get locked, and the simpler the recovery

## When to contact WeGive support

If you've replaced the key, confirmed it works via Test Connection, and retried the locked records but are still seeing persistent errors, contact WeGive support with:

* The **Integration Log IDs** of a few failing entries
* The **error message** from the Details view
* Whether the integration was auto-disabled or still enabled when you noticed the problem


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