Site Connection — Technical Reference
Technical details of the OAuth PKCE connection flow and developer configuration options for local and staging environments.
The OAuth PKCE Flow
When you click Connect to Benecaster, the plugin calls its internal license start endpoint:
POST /benecaster/v1/license/oauth/start
This generates a PKCE code verifier and challenge pair, stores the verifier in a transient, and returns a fully parameterized authorization URL pointing to benecaster.com/connect.
Your browser is redirected to that URL. After you log in and click Authorize, the license server issues an authorization code and redirects back to your WordPress admin. The plugin’s callback handler exchanges the code and the stored PKCE verifier for a per-show token. If the PKCE check passes, the token is stored and the connection is active.
Why PKCE? PKCE prevents authorization code interception — even if the code is observed in transit, it can’t be used without the verifier that never leaves the plugin. This is standard OAuth 2.0 practice for public clients.
Site Verification
During the token exchange, Benecaster.com sends an outbound probe to your site’s verify endpoint:
GET /wp-json/benecaster/v1/verify?code=probe&nonce=probe&show_uuid=probe
This confirms that the WordPress site initiating the connection is publicly reachable at the claimed URL and is running the Benecaster plugin. The probe must return HTTP 200 with a valid JSON response. If it fails, the connection is rejected with a site_verification_failure error. See Connection Troubleshooting → for common causes and fixes.
Local and Staging Environments
Define the BENECASTER_LICENSE_URL constant (typically in wp-config.php) to redirect the plugin to a local or staging license server:
define( 'BENECASTER_LICENSE_URL', 'https://license.yourdomain.test' );
When set:
- The Connect button builds authorization URLs against the specified base URL instead of
https://benecaster.com - The daily
/validateping targets the specified URL - The OAuth callback uses the specified URL for the token exchange
The flow is otherwise identical. The site verification probe still fires from whatever license server is at the target URL.
Error Code Reference
| Error code | Cause |
|---|---|
invalid_grant |
Authorization code expired (single-use, short-lived) or already consumed |
pkce_mismatch |
Code verifier didn’t match the stored challenge — typically means the browser cleared session storage between the click and the callback |
site_url_mismatch |
get_home_url() on callback doesn’t match the URL on the Benecaster.com account record |
site_verification_failure |
Outbound probe from Benecaster.com to your site failed — probe URL and response are in the admin notice |
rate_limited |
Too many connection attempts in a short window |
access_denied |
User clicked Cancel on the benecaster.com authorization screen |