ForgeWP

WordPress & Separate Frontends

Choose a session architecture and verify the installed account workflow.

Deploy the account workflow

For an exported theme, begin with WordPress cookie authentication. Build/export the theme, install it, create the required public account Pages, and assign their generated templates. Test the URLs that actually exist on the installed site.

Table · 3 columns
Deployment
Account/session owner
Additional setup
WordPress theme
WordPress and its cookies
Public account routes, working mail, account-specific cache behavior
Separate frontend with cookies
WordPress on another origin/path
Explicit API base, cookie credentials and origin policy supported by the deployment
Separate frontend with JWT
A JWT-capable WordPress backend
Token issuance/validation plugin, API origin, token lifecycle and permission checks
Start with the theme's normal deployment

A separate frontend introduces origin and token decisions. Installing Auth alone does not install a JWT server or configure cross-origin cookies.

API base selection

Both paths first honor window.FORGEWP_API_URL, then the compiled Vite values FORGEWP_API_URL and VITE_WP_API_URL. Without an explicit base, the generated home setting supplies the WordPress subdirectory for same-origin requests. Bases are normalized without a trailing slash; the action appends /wp-json/....

The provider additionally recognizes process environment aliases FORGEWP_API_URL, NEXT_PUBLIC_WP_API_URL, and WP_API_URL. Those aliases are not a documented standalone-hook fallback. A browser only sees environment values explicitly exposed by its bundler; placing a value in a server environment does not automatically expose it to browser code.

JWT detection recognizes window.FORGEWP_JWT_AUTH, compiled FORGEWP_JWT_AUTH, and VITE_WP_JWT_AUTH. The provider additionally recognizes process aliases FORGEWP_JWT_AUTH, NEXT_PUBLIC_WP_JWT_AUTH, and WP_JWT_AUTH. Prefer compiler headless configuration for the exported theme integration.

Account email destinations

The server uses home_url() as the default frontend base for verification and reset links. A separate frontend can set the WordPress server constant FORGEWP_FRONTEND_ORIGIN to its public base URL. This is distinct from headless.apiUrl, which identifies the API backend. Preserve any required frontend path prefix and provide both verification and reset routes.

wp-config.php (separate frontend example)
1define('FORGEWP_FRONTEND_ORIGIN', 'https://app.example.test');

Optional JWT behavior

The client uses /wp-json/jwt-auth/v1/token and the provider checks /wp-json/jwt-auth/v1/token/validate during restoration. Tokens are stored as forgewp_jwt_token. Local JWT logout removes the token; revocation of an already-issued token is a backend responsibility.

Provider and standalone JWT restoration are not identical. Standalone restoration decodes stored payloads; the provider performs a validation request, but its current network-error fallback can still restore display state from the payload. Neither decoded display state nor a visible gate is proof that the backend accepted a token. Protected backend requests must validate and authorize it independently.

Acceptance checklist

  • Test login, reload, logout, and subsequent protected-page requests with real WordPress accounts.
  • Test registration disabled/enabled, default role, approved metadata and each verification/auto-login policy.
  • Test verification delivery, resend failures, invalid/used links and actual session establishment.
  • Test recovery delivery, reset-key expiry/reuse and login using the new password.
  • Test a subscriber and an account with the required editorial capability.
  • Check subdirectory paths, login/verification/reset destinations, redirects, caches and cross-origin behavior where applicable.

These checks remain separate from mock preview and generated-PHP tests. The project tracker records live WordPress acceptance as deferred; exporting the theme does not certify a particular deployment's authentication setup.