Authentication/guides/Access Control

Protected Pages & Redirects

Declare page-wide authentication and capability requirements in pageConfig.

On This Page

Protect an entire page

Use pageConfig when an exported Page template should require login before its content is served. A component gate only wraps part of a page.

src/app/pages/EditorialDashboard.tsx

1import { definePageConfig } from "@forgewp/react/config"
2
3export const pageConfig = definePageConfig({
4  protected: true,
5  allowed: "edit_posts",
6  redirect: "/login",
7})
8
9export default function EditorialDashboard() {
10  return (
11    <main>
12      <h1>Editorial dashboard</h1>
13      <p>Your editing workspace.</p>
14    </main>
15  )
16}

definePageConfig supplies type assistance. A plain exported pageConfig object is also supported. Keep protected: true with the access declaration; allowed alone is not the documented way to protect a Page.

Table · 2 columns


Setting	Purpose
`protected`	Enables page-wide protection
`allowed`	Optional WordPress capability required in addition to login
`redirect`	Destination for signed-out visitors; defaults to /login

The compiler's page-config plugin injects useWpPageProtect() for local navigation and emits a protection marker. Export generates WordPress checks before the Page template's content. A signed-in account without the required capability is redirected to the site root. When installed email verification is enabled and the account is explicitly unverified, the generated protected Page redirects to its verification page.

Login policy and page policy are separate

blockLoginUntilVerified controls password-login behavior. Protected Page verification checks apply when email verification is enabled. Test both the account policy and the destination Page.

Pick a real destination

Use a developer-controlled path such as /login, adjusted for the site's installation path. The existing scaffold also uses template:login-page to resolve the installed login Page; local preview derives its route from that template name. WpPageLink-generated page-link markers are also handled by the protection runtime/compiler. Use the normal page-link workflow rather than writing those internal markers yourself.

Your login page should be public. A protected login page redirecting back to itself creates a navigation loop. Exporting a template does not by itself select the URL: assign it to a real WordPress Page and verify its permalink.

When to call the hook directly

useWpPageProtect(config) is exported for components that need the local client redirect behavior. It accepts the same protected, allowed, and redirect fields through WpPageConfig. A direct hook call is not a substitute for the exported Page's pageConfig or endpoint authorization.

Check each account state

Table · 2 columns


Visitor	Expected installed Page behavior
Signed out	Redirect to the configured login destination
Signed in with required capability	Serve the Page after verification checks
Signed in without required capability	Redirect to site root
Explicitly unverified while verification is enabled	Redirect to verification page

Verify on the installed theme with separate accounts. Keep protected responses out of shared public caches unless the deployment correctly separates account-specific content.