Connecting Your Site to Benecaster

Benecaster uses an OAuth flow to link your WordPress site to your Benecaster.com account. Each paid show on your site gets its own connection — one show can be connected while another is not. This page covers how to initiate the flow, what happens during and after it, and how to recover from common error states.

Where the Connect Button Appears

The Connect to Benecaster button appears in two places:

Setup Wizard → Step 6 (Subscribers) — shown on the paid path when you choose “Yes — I want paying subscribers.” This is the primary entry point for new installations.
Settings → Shows → [Show] → Settings → Subscription tab — shown for each paid show that has no active connection (not connected, or after a disconnect). Free shows render a de-emphasized “no license needed” note on this tab that links to the Visibility tab instead.

If the button is disabled with the message “Finish creating your show first,” you need to save at least a show name in Step 1 of the wizard before the button becomes active. The OAuth flow requires a show to bind the token to.

Note: The Connect button is no longer on Settings → Account. The Account tab shows a read-only portfolio of all shows and their connection status, with links that take you to each show’s Subscription tab to initiate a connection.

Starting the Connection

Click Connect to Benecaster. The plugin:

Calls its internal license start endpoint (POST /benecaster/v1/license/oauth/start) to build a PKCE-parameterized authorization URL.
Redirects your browser to benecaster.com/connect.

On benecaster.com, log in to (or create) your Benecaster account and click Authorize. Benecaster.com verifies that the connection request came from your site, issues a token, and redirects your browser back to your WordPress admin.

Once you’re back in the WordPress admin, the per-show token is stored and the connection is active.

Local or staging environments: If you’ve defined the BENECASTER_LICENSE_URL constant to point at a local or staging license server, the Connect button uses that base URL instead of https://benecaster.com. The flow is otherwise identical.

After a Successful Connection

A green admin notice confirms the site is connected: “Benecaster connected — Show Name is now active.”
The show’s Settings → Subscription tab shows the masked token prefix and granted date, plus a Deactivate this show’s license button.
Settings → Account shows the show’s status as Connected in the Shows portfolio panel.
The setup wizard (if you were in Step 6) enables its Continue button.

Error States and Recovery

All connection errors send you back to wherever you started (wizard or Settings). Each error asks you to click Connect to Benecaster again — the flow generates a fresh PKCE state on every attempt, so retrying is always safe.

Error	What it means	Recovery
Invalid grant	The authorization code expired or was already used. Codes are single-use and expire quickly.	Click Connect to Benecaster again.
PKCE mismatch	The code verifier sent on callback didn’t match the challenge. Usually means the browser cleared storage between clicks.	Click Connect to Benecaster again.
Site URL mismatch	Benecaster.com verified the connection but `get_home_url()` on your site differs from the URL it has on record. Happens if your site URL changed since your last login, or if you’re on a staging clone.	Ensure your WordPress site URL is correct (Settings → General → WordPress Address), then click Connect to Benecaster again. If you’re on a staging site, see Working with Staging Sites.
Site verification failure	Benecaster.com couldn’t reach your site’s verify endpoint during the token exchange. The notice names the exact URL it tried to reach and shows the HTTP result (or error).	See troubleshooting steps below. Click Connect to Benecaster again after resolving.
Rate limited	Too many connection attempts in a short window.	Wait a few minutes, then click Connect to Benecaster again.
Access denied	You clicked Cancel or denied the authorization on benecaster.com.	Click Connect to Benecaster again to restart from the beginning.
Network error	A transient network error interrupted the callback.	Click Connect to Benecaster again.

Site Verification Failure — Detailed Troubleshooting

When site verification fails, the admin notice names the exact URL Benecaster.com tried to reach, along with the HTTP response code and elapsed time (or a cURL error if the request never completed). This information helps you diagnose the cause.

The probe URL looks like:

https://yoursite.com/wp-json/benecaster/v1/verify?code=probe&nonce=probe&show_uuid=probe

Note the show_uuid query parameter — if you’ve seen older documentation referring to show_id, that parameter was renamed.

Three common causes:

Your site is not publicly accessible. Local development installs (localhost, .test, .local), sites behind a VPN, sites in maintenance mode, and sites that require HTTP authentication all fail this check — Benecaster.com cannot reach them from the internet. Use a staging tunnel (like ngrok) or use the BENECASTER_LICENSE_URL constant to point at a local license server.
A security plugin or WAF is blocking the request. Some WordPress security plugins (Wordfence, iThemes Security) or CDN WAF rules block automated requests that look like probes. Temporarily disable your WAF or add an exception for the /wp-json/benecaster/v1/verify path, then retry.
Your server’s SSL certificate is untrusted or expired. Benecaster.com will not reach an endpoint over HTTPS with an invalid certificate. Renew your certificate or check that your certificate chain is complete. You can verify with curl -I https://yoursite.com/wp-json/benecaster/v1/verify?code=probe&nonce=probe&show_uuid=probe from an external server.

Reading the probe result in the notice:

HTTP 200, Xms — the probe reached the endpoint and got a valid response. If you still see this error, the response content may have been malformed — contact support.
HTTP 4xx or HTTP 5xx — the request arrived but the server rejected it. The most common cause is an overly aggressive WAF rule.
cURL error: ... — the connection failed at the network level (DNS, timeout, SSL, TCP refused). The cURL error string identifies the network-level issue.

Reconnect State

What triggers it: If Benecaster’s daily /validate ping returns HTTP 401 on two consecutive runs for the same show, Benecaster sets that show into reconnect state. Two consecutive failures are required — a single 401 is treated as a possible transient proxy anomaly and is logged but does not flag the show.

What you see: An admin notice at the top of every Benecaster page:

Action required: Your Benecaster connection for Show Name needs to be refreshed. [Reconnect to Benecaster →]

The notice links directly to the Connect button on that show’s Settings → Subscription tab.

Per-show scope: Reconnect state is per-show. If you have two shows connected and one token is revoked, only that show enters reconnect state — the other show’s connection is unaffected and continues to validate normally.

Common causes of reconnect state:

Customer revoked the token from the Licenses panel on their Benecaster Customer Dashboard on benecaster.com.
Operator revoked the token from the Customer Detail page in the Benecaster.com admin.
GDPR erasure cascade removed the token record.
License expired or was cancelled.

How to clear it: Click Reconnect to Benecaster in the notice (or open that show’s Settings → Subscription tab and click the Reconnect button there) and complete the OAuth flow again. A successful /validate ping after reconnection clears the reconnect flag and resets the strike counter automatically.

Disconnecting

To disconnect a show, open Settings → Shows → [Show] → Settings → Subscription and click Deactivate this show’s license. This revokes the token on benecaster.com and clears the local per-show token. The show returns to unlicensed state — you can reconnect at any time by clicking Connect to Benecaster again.

Disconnecting a show does not delete subscriber data or affect other connected shows.