REST API Overview

Benecaster exposes a REST API under the benecaster/v1 namespace on your WordPress site. These endpoints power the Benecaster admin UI and are also available for custom integrations — syncing subscribers to a CRM, building donor boards, triggering cache clears from external code, and similar tasks.

All endpoints live at:

https://yoursite.com/wp-json/benecaster/v1/

Authentication

Endpoints fall into two categories:

Public endpoints — no authentication required. Used for cross-site callbacks and listener-facing requests (listener account actions, donation submissions, Stripe payment intents). Public endpoints are rate-limited per IP to prevent abuse.

Protected endpoints — require manage_options capability. Used for all admin data reads and writes.

Browser requests (nonce-based)

The Benecaster admin UI sends requests using WordPress cookie authentication. The nonce is included in the X-WP-Nonce header:

X-WP-Nonce: {nonce}

The nonce is generated server-side and exposed to JavaScript via wp_localize_script. This is handled automatically — you do not need to configure it unless you are building a custom admin extension.

Automation and server-to-server requests (Application Passwords)

For scripts, integrations, and external services that call protected endpoints outside of the browser session:

1. Create a dedicated WordPress administrator account for API access. Do not use your own admin credentials — if the integration is compromised, a dedicated account can be revoked without locking yourself out.
2. Go to Users → [dedicated user] → Application Passwords. Generate a new password and label it with the integration name (e.g. “Zapier sync”, “CRM export”).
3. Use HTTP Basic Auth with your WordPress username and the generated Application Password:

Authorization: Basic base64(username:application-password)

The dedicated account must have the Administrator role — the protected endpoints require manage_options, which is an Administrator-only capability in a standard WordPress installation.

Revoke Application Passwords immediately when an integration is decommissioned. Each password is independent — revoking one does not affect others.

Rate Limiting

All benecaster/v1 endpoints are rate-limited per IP address. Exceeding a limit returns HTTP 429 with a Retry-After header indicating when you may retry:

{
  "code":    "benecaster_rate_limited",
  "message": "Too many requests. Please wait before retrying.",
  "data":    { "status": 429 }
}

Default limit: 300 requests per 5 minutes.

Tighter limits on specific endpoints:

Developers can adjust limits using the benecaster_rest_rate_limit_buckets filter, or exempt specific integrations using benecaster_rest_rate_limit_skip.

Error Responses

All error responses follow the standard WordPress REST API format:

{
  "code":    "benecaster_error_slug",
  "message": "Human-readable description.",
  "data":    { "status": 400 }
}

Common HTTP status codes:

Endpoint Groups