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

# API Overview & Authentication

> WeGive Help Center article: API Overview & Authentication

# API Overview & Authentication

The WeGive REST API lets developers read and write organization data — donors, transactions, campaigns, communication lists, and more — from external systems. This article covers what you need to know to make your first authenticated request.

## Overview

The WeGive API is:

* **REST-style** over HTTPS, with JSON request and response bodies.
* **Organization-scoped.** Every API key belongs to a single organization, and all data accessed through the API is scoped to that organization.
* **Versionless at the URL level.** All endpoints live under the `/api/` prefix today; we don't currently use a `/v1/` or `/v2/` segment in the path.

The main resource categories you'll interact with include:

* Donors and households
* Transactions, scheduled (recurring) donations, and pledges
* Campaigns, fundraisers, and events
* Communication lists and messages
* Custom fields, tags, and notes

A full endpoint reference is published separately at `https://docs.api.wegive.com`.

## Base URL

Use the base URL that matches your environment:

| Environment | Base URL |
| - | - |
| Production | `https://api.wegive.com` |
| Sandbox | `https://api.sandbox.wegive.com` |
| Staging | `https://api.staging.wegive.com` |

All examples in this article use the production base URL.

## Authentication

The WeGive API uses **bearer token authentication** via personal access tokens. Every request must include an `Authorization` header containing your token:

```
Authorization: Bearer {your_api_key}
```

Tokens are issued in the format `{token_id}|{secret}` — both halves together make up the value you send in the `Authorization` header. Treat the entire string as a secret.

### Generating an API key

Creating, viewing, and revoking API keys requires the **Developer** role (or a custom role with the `developer.api` permission) — if you don't see the API section in Settings, that's why.

1. In the WeGive dashboard, go to **Settings → API**.
2. Note your **Organization ID** at the top of the page — some integrations need it in addition to the API key.
3. Click **Create New API Key**.
4. Copy the key from the dialog and store it somewhere secure (a password manager or your application's secret store).

**Important:** The full API key is shown only once, at creation time. If you lose it, you'll need to revoke and regenerate it.

### Key limits

* **One API key per user.** If you try to create a second key for the same user, the request will fail. To rotate a key, revoke the existing one first, then create a new one.
* Keys are tied to the **organization**, not the user — they continue to grant access to organization data even if the user who created them is later removed.

### Testing your key

Once you have a key, you can confirm it's working with a quick request to the test endpoint:

```
curl https://api.wegive.com/api/dashboard/personal-access-tokens/test \
  -H "Authorization: Bearer {your_api_key}"
```

A `200` response with your organization ID confirms the key is valid and active.

## Making your first request

Here's a minimal example that lists donors for your organization:

```
curl https://api.wegive.com/api/dashboard/donors \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Accept: application/json"
```

In JavaScript:

```
const response = await fetch("https://api.wegive.com/api/dashboard/donors", {
  headers: {
    Authorization: `Bearer ${process.env.WEGIVE_API_KEY}`,
    Accept: "application/json",
  },
});

const data = await response.json();
```

In Python:

```
import os
import requests

response = requests.get(
    "https://api.wegive.com/api/dashboard/donors",
    headers={
        "Authorization": f"Bearer {os.environ['WEGIVE_API_KEY']}",
        "Accept": "application/json",
    },
)

data = response.json()
```

## Errors

The API uses standard HTTP status codes to signal success and failure:

| Status | Meaning |
| - | - |
| `200` / `201` | Success |
| `400` | Bad request — your payload is missing fields or has invalid values |
| `401` | Unauthenticated — your API key is missing or invalid |
| `403` | Forbidden — your key is valid but doesn't have access to this resource |
| `404` | Not found — the resource doesn't exist or isn't visible to your organization |
| `422` | Unprocessable — validation failed (e.g., trying to write to a read-only field) |
| `429` | Too many requests — you've hit a rate limit |
| `500` | Server error — something went wrong on our side |

Error responses follow Laravel's default JSON shape, with a `message` field describing what went wrong. For validation errors (`422`), an `errors` object lists the offending fields.

## Rate limits

The production API enforces the following limits, applied per API key (or per IP for unauthenticated requests):

| Operation type | Limit |
| - | - |
| General API requests | 360 requests / minute |
| Money-moving operations (charges, payouts) | 6 requests / minute, plus 10 requests / day |
| Checkout session create/update | 200 requests / minute |
| AI assistant endpoints | 30 requests / minute |
| Forgot-password endpoint | 2 requests / minute |

When you exceed a limit, the API returns `429 Too Many Requests`. We recommend implementing exponential backoff with retries on `429` responses for any production integration.

## Security best practices

* Store API keys in a secrets manager or environment variables, never in source code or client-side JavaScript.
* Rotate keys on a regular schedule and immediately if you suspect a leak.
* Revoke unused keys from **Settings → API**.
* Use the sandbox environment for development and testing — never run experiments against production data.

## Need help?

If you run into an issue with authentication or the API more broadly, contact WeGive Support and include the request URL, the response status, and the response body (with your API key redacted).


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