Authentication/guides/Getting Started

Overview & Architecture

Understand what ForgeWP Auth provides and where authentication happens.

On This Page

Getting started with ForgeWP Auth

Authentication answers “who is signed in?” Authorization answers “what may this person do?” ForgeWP Auth gives React components a way to display the current user, submit account actions, and choose content based on WordPress capabilities.

In an exported WordPress theme, WordPress owns the accounts and sessions. The compiler generates the Auth endpoints and settings when Auth is enabled. React supplies the interface; the server decides whether a request is allowed.

Start with one account workflow

Build a login form, a signed-in greeting, and a logout button under one provider first. Once that works, add registration and access rules.

How the pieces connect

Flowchart

Rendering diagram...

The form collects input; WordPress decides the result. Local preview substitutes mock account behavior for that server step.

Choose the right environment

Table · 3 columns


Environment	Where user information comes from	What you can verify
Local Vite preview	Mock users, roles, and a browser-local preview session	Layout, form states, and mock account interactions
Exported WordPress theme	WordPress accounts, session cookies, and generated session data	Real sign-in and account workflows after installation
Separately hosted frontend	An explicitly configured API and optional JWT integration	Deployment-specific authentication after backend setup

A local preview account is separate from a WordPress account. Exporting a theme does not convert a successful mock login into a WordPress session.

Start with the exported WordPress theme workflow. A separately hosted frontend needs its own API origin, token-plugin, and deployment checks; installing @forgewp/auth alone does not provide a JWT server.

The main building blocks

Table · 2 columns


API	Purpose
`WpAuthProvider`	Shares authentication state and actions with its React descendants
`useWpAuth()`	Returns account actions, operation state, and errors
`useWpUser()`	Returns the current `WpUser`, or `null` when signed out
`useWpCapability(name)`	Returns whether the current user has a named capability
`WpLoginForm`	Provides a ready-made login interface inside the provider
`WpAuthGate`	Chooses signed-in content or a fallback
`WpCapabilityGate`	Chooses content using a capability such as `edit_posts`

A capability is a permission key. For example, edit_posts is a permission; subscriber is a role name. Use capability names with capability checks.

Gates control the content they wrap. Protect an entire exported page through its pageConfig, and enforce permissions on every backend endpoint that exposes protected data or performs an action.

React authoring and WordPress rendering

For a static exported gate, the compiler turns the React wrapper into a WordPress condition. This excerpt illustrates the same two content branches in each environment:

An exported authentication gate

React (Source)React template excerpt

React template excerpt

1<WpAuthGate fallback={<p>Sign in</p>}>
2  <p>Member content</p>
3</WpAuthGate>

WordPress (Compiled)Generated PHP excerpt

Generated PHP excerpt

1<?php if ( is_user_logged_in() ) : ?>
2<p>Member content</p>
3<?php else : ?>
4<p>Sign in</p>
5<?php endif; ?>

Choose the right protection boundary

A gate selects the content inside it. Use page protection for an entire exported page, and check permissions in backend endpoints that return private data.

Continue with Installation & First Login, then Sessions & Local Preview.