Hidayat Mahetar

HeadlessKey – JWT Auth extends the REST API to provide a robust and secure authentication system using JSON Web Tokens (JWT). Designed for Headless WordPress, it enables seamless user authentication, registration, and session management via standard REST endpoints.
<h3>Key Features</h3>
<ul>
<li>Standard JWT Authentication: Secure user authentication using industry-standard RFC 7519 tokens.</li>
<li>Multiple Algorithms: Support for <code>HS256</code>, <code>RS256</code>, and <code>ES256</code> signing algorithms.</li>
<li>Comprehensive Endpoints: Ready-to-use endpoints for Login, Register, Token Refresh, and Password Management.</li>
<li>Single Sign-On (SSO): Connect multiple sites with a secure, headers-based SSO exchange mechanism.</li>
<li>Role-Based Access Control (RBAC): Configure public or authenticated access for every endpoint.</li>
<li>Brute Force Protection: Protects against attacks by locking users/IPs after failed attempts.</li>
<li>Activity Logs: Detailed audit trail of all authentication events, including IP and device data.</li>
<li>Security Webhooks: Real-time JSON events sent to your external services for monitoring key actions.</li>
<li>Device Limits: Restrict the number of active devices/sessions per user.</li>
<li>Developer Friendly: Extensive hooks and filters for deep customization.</li>
</ul>
<h3>Configuration</h3>
<h3>Secret Key</h3>
The plugin uses a secret key to sign tokens. By default, a secure random key is generated. For better security and consistency across environments, define your key in <code>wp-config.php</code>:
<pre><code>define('headlesskey_SECRET_KEY', 'your-long-random-secure-string');
</code></pre>
You can generate a strong salt here: <a href="https://api.wordpress.org/secret-key/1.1/salt/" rel="nofollow ugc">WordPress Salt Generator</a>
<h3>CORS Support</h3>
Cross-Origin Resource Sharing (CORS) is enabled by default to allow frontend applications to connect. To disable or customize it via constant:
<pre><code>define('headlesskey_CORS', true); // or false to disable
</code></pre>
<h3>REST API Namespace</h3>
By default, endpoints are under <code>wp-json/wpauthapi/v1</code>. You can customize this namespace:
<pre><code>define('headlesskey_REST_NAMESPACE', 'my-custom-auth');
define('headlesskey_REST_VERSION', 'v2');<h3>Endpoints</h3>
</code></pre>
The plugin adds the following endpoints under the <code>/wp-json/headlesskey/v1</code> namespace:
 Endpoint 
 HTTP Verb 
 Description
 <code>/token</code> 
 POST 
 Login: Exchange username/password for a JWT.
 <code>/token/validate</code> 
 POST 
 Validate: Check if a token validity.
 <code>/token/refresh</code> 
 POST 
 Refresh: Exchange a valid token for a new one (rotation).
 <code>/token/revoke</code> 
 POST 
 Logout: Invalidate a specific token.
 <code>/register</code> 
 POST 
 Register: Create a new user account.
 <code>/login</code> 
 POST 
 Profile: Login and get full user profile data in one request.
 <code>/forgot-password</code> 
 POST 
 Recover: Request a password reset via Link or OTP.
 <code>/reset-password</code> 
 POST 
 Reset: Set a new password using a token or OTP.
 <code>/change-password</code> 
 POST 
 Update: Change password for authenticated user.
 <code>/sso/exchange</code> 
 POST 
 SSO: Exchange a remote site token for a local session.
<h3>1. Login (Generate Token)</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/token</code> 
Description: Authenticate a user and generate a JWT token.
Request: 
 <code>json 
{ 
 "username": "admin", 
 "password": "secret-password" 
}</code>
Response: 
 <code>json 
{ 
 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", 
 "expiration": "2023-10-27T10:00:00+00:00", 
 "expires_in": 3600, 
 "user": { 
 "ID": 1, 
 "user_login": "admin", 
 "user_email": "admin@example.com", 
 "display_name": "Administrator", 
 "roles": ["administrator"] 
 }, 
 "refreshable": true, 
 "jti": "545086b9-450f-488b-a70d-3047d14d1101" 
}</code>
<h3>2. Validate Token</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/token/validate</code> 
Description: Validate if an existing token is valid.
Request: 
 <code>json 
{ 
 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." 
}</code>
Response: 
 <code>json 
{ 
 "valid": true, 
 "data": { 
 "iss": "https://example.com", 
 "iat": 1698393600, 
 "exp": 1698397200, 
 "data": { 
 "ID": 1, 
 "user_login": "admin" 
 } 
 } 
}</code>
<h3>3. Refresh Token</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/token/refresh</code> 
Description: Rotate an expiring token for a fresh one.
Request: 
 <code>json 
{ 
 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." 
}</code>
Response: 
 <code>json 
{ 
 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.new...", 
 "expiration": "2023-10-27T11:00:00+00:00", 
 "user": { 
 "ID": 1, 
 "user_login": "admin" 
 }, 
 "jti": "new-uuid-v4" 
}</code>
<h3>4. Revoke Token (Logout)</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/token/revoke</code> 
Description: Invalidate a token immediately.
Request: 
 <code>json 
{ 
 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." 
}</code>
Response: 
 <code>json 
{ 
 "message": "Token revoked successfully." 
}</code>
<h3>5. Register User</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/register</code> 
Description: Create a new user account.
Request: 
 <code>json 
{ 
 "username": "johndoe", 
 "email": "john@example.com", 
 "password": "secure-password", 
 "name": "John Doe" 
}</code>
Response: 
 <code>json 
{ 
 "user_id": 45, 
 "user": { 
 "ID": 45, 
 "user_login": "johndoe", 
 "user_email": "john@example.com", 
 "display_name": "John Doe", 
 "roles": ["subscriber"] 
 }, 
 "token_response": { 
 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...", 
 "expiration": "2023-10-27T10:00:00+00:00" 
 } 
}</code>
<h3>6. User Profile (Login Extended)</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/login</code> 
Description: Alternative login endpoint that returns cleaner profile structure.
Request: 
 <code>json 
{ 
 "username": "admin", 
 "password": "secret-password" 
}</code>
Response: 
 <code>json 
{ 
 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", 
 "expiration": "2023-10-27T10:00:00+00:00", 
 "user": { 
 "ID": 1, 
 "user_login": "admin", 
 "user_email": "admin@example.com", 
 "display_name": "Administrator", 
 "roles": ["administrator"] 
 } 
}</code>
<h3>7. Forgot Password</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/forgot-password</code> 
Description: Initiate password recovery. Note: <code>delivery</code> can be <code>link</code> or <code>otp</code>.
Request: 
 <code>json 
{ 
 "login": "admin@example.com", 
 "delivery": "link" 
}</code>
Response: 
 <code>json 
{ 
 "message": "Password reset email sent." 
}</code>
<h3>8. Reset Password</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/reset-password</code> 
Description: Reset password using the token sent via email or OTP.
Request (Link method): 
 <code>json 
{ 
 "login": "admin@example.com", 
 "password": "new-secure-password", 
 "token": "generated-reset-key" 
}</code>
Response: 
 <code>json 
{ 
 "message": "Password updated successfully." 
}</code>
<h3>9. Change Password</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/change-password</code> 
Description: Change password for currently authenticated user. Requires <code>Authorization</code> header.
Headers: 
 Authorization: Bearer 
Request: 
 <code>json 
{ 
 "current_password": "old-password", 
 "new_password": "new-secure-password" 
}</code>
Response: 
 <code>json 
{ 
 "message": "Password changed successfully. Please login again." 
}</code>
<h3>10. SSO Token Exchange</h3>
Endpoint: <code>POST /wp-json/headlesskey/v1/sso/exchange</code> 
Description: Securely exchange a token from a connected remote site for a local authentication session. This powers the distributed Single Sign-On network.
Request: 
 <code>json 
{ 
 "site_key": "remote-site-id", 
 "token": "remote-jwt-token", 
 "signature": "hmac-sha256-signature" 
}</code>
Response: 
Returns a standard Login response (Token + User Data) if the signature is valid.

HeadlessKey – JWT Auth

A complete authentication solution for Headless WordPress applications using JWT, supporting Registration, SSO, RBAC, and advanced Security features.

Sébastien Dumont

CoCart Headless

This free add-on for <a href="https://cocartapi.com/?utm_medium=wp.org&utm_source=wordpressorg&utm_campaign=readme&utm_content=cocart" rel="nofollow ugc">CoCart</a> allows you to authenticate the Cart API via JSON Web Tokens as an authentication method.
★★★★★
<blockquote>
An excellent plugin, which makes building a headless WooCommerce experience a breeze. Easy to use, nearly zero setup time. <a href="https://wordpress.org/support/topic/excellent-plugin-8062/" rel="ugc">Harald Schneider</a>
</blockquote>
<h3>Key Features</h3>
<ul>
<li>Standard JWT Authentication: Implements the industry-standard <a href="https://datatracker.ietf.org/doc/html/rfc7519" rel="nofollow ugc">RFC 7519</a> for secure claims representation.</li>
<li>Simple Endpoints: Offers clear endpoints for generating and validating tokens.</li>
<li>Configurable Secret Key: Define your unique secret key via <code>wp-config.php</code> for secure token signing.</li>
<li>Multiple signing algorithms: <code>HS256</code>, <code>HS384</code>, <code>HS512</code>, <code>RS256</code>, <code>RS384</code>, <code>RS512</code>, <code>ES256</code>, <code>ES384</code>, <code>ES512</code>, <code>PS256</code>, <code>PS384</code>, <code>PS512</code></li>
<li>Rate Limiting: Controlled specifically for refreshing and validating tokens.</li>
<li>Helpful Debugging: Detailed logs of authentication issues to help figure out exactly what happened and fix it faster.</li>
<li>WP-CLI Commands: Useful <a href="https://github.com/cocart-headless/cocart-jwt-authentication/blob/master/docs/wp-cli.md" rel="nofollow ugc">commands to handle tokens</a> – whether you need to check, destroy or create new ones, or clean up old ones.</li>
<li>Developer Hooks: Provides <a href="https://github.com/cocart-headless/cocart-jwt-authentication/blob/master/docs/filters.md" rel="nofollow ugc">filters</a> and <a href="https://github.com/cocart-headless/cocart-jwt-authentication/blob/master/docs/hooks.md" rel="nofollow ugc">hooks</a> for more configuration to your requirements.</li>
</ul>
JSON Web Tokens are an open, industry standard method for representing claims securely between two parties.
For more information, <a href="https://github.com/cocart-headless/cocart-jwt-authentication/blob/master/docs/concepts.md" rel="nofollow ugc">read the core concept</a> on what this plugin does and can do.
<h3>📄 Documentation</h3>
See documentation on how to <a href="https://github.com/cocart-headless/cocart-jwt-authentication/blob/master/docs/guide.md" rel="nofollow ugc">get setup</a>, <a href="https://github.com/cocart-headless/cocart-jwt-authentication/blob/master/docs/filters.md" rel="nofollow ugc">filters</a> and <a href="https://github.com/cocart-headless/cocart-jwt-authentication/blob/master/docs/hooks.md" rel="nofollow ugc">hooks</a> with examples to help configure JWT Authentication to your needs.
Once ready to use, see the <a href="https://github.com/cocart-headless/cocart-jwt-authentication/blob/master/docs/quick-start.md" rel="nofollow ugc">quick start guide</a>. There is also an <a href="https://github.com/cocart-headless/cocart-jwt-authentication/blob/master/docs/advanced-configuration.md" rel="nofollow ugc">advanced configuration</a> for using RSA Keys.
★★★★★
<blockquote>
Amazing Plugin. I’m using it to create a react-native app with WooCommerce as back-end. This plugin is a life-saver! <a href="https://wordpress.org/support/topic/amazing-plugin-1562/" rel="ugc">Daniel Loureiro</a>
</blockquote>
<h4>👍 Add-ons to further enhance CoCart</h4>
We also have other add-ons that extend CoCart to enhance your headless store development.
<ul>
<li><a href="https://wordpress.org/plugins/cocart-cors/" rel="ugc">CoCart – CORS</a> enables support for CORS to allow CoCart to work across multiple domains.</li>
<li><a href="https://wordpress.org/plugins/cocart-rate-limiting/" rel="ugc">CoCart – Rate Limiting</a> enables the rate limiting feature.</li>
</ul>
These add-ons of course come with support too.
<h3>💜 Need Support?</h3>
We aim to provide regular support for the CoCart plugin via <a href="https://cocartapi.com/community/?utm_medium=website&utm_source=wpplugindirectory&utm_campaign=readme&utm_content=readmelink" rel="nofollow ugc">our Discord community server</a>. Please understand that we do prioritize support for our <a href="https://cocartapi.com/pricing/?utm_medium=website&utm_source=wpplugindirectory&utm_campaign=readme&utm_content=readmelink" rel="nofollow ugc">paying customers</a>.
<h3>⌨️ Join our growing community</h3>
On Discord, we have a community of developers, WordPress agencies, and shop owners building the fastest and best headless WooCommerce stores with CoCart.
Come and <a href="https://cocartapi.com/community/?utm_medium=wp.org&utm_source=wordpressorg&utm_campaign=readme&utm_content=cocart" rel="nofollow ugc">join our community</a>
<h3>🐞 Bug reports</h3>
Bug reports for CoCart JWT Authentication are welcomed in the <a href="https://github.com/cocart-headless/cocart-jwt-authentication" rel="nofollow ugc">CoCart JWT Authentication repository on GitHub</a>. Please note that GitHub is not a support forum, and that issues that aren’t properly qualified as bugs will be closed.
<h3>More information</h3>
<ul>
<li><a href="https://cocartapi.com/?utm_medium=website&utm_source=wpplugindirectory&utm_campaign=readme&utm_content=readmelink" rel="nofollow ugc">Website</a>.</li>
<li><a href="https://cocartapi.com/docs/?utm_medium=website&utm_source=wpplugindirectory&utm_campaign=readme&utm_content=readmelink" rel="nofollow ugc">Documentation</a></li>
<li><a href="http://eepurl.com/dKIYXE" rel="nofollow ugc">Subscribe to updates</a></li>
<li>Like, Follow and Star on <a href="https://www.facebook.com/cocartforwc/" rel="nofollow ugc">Facebook</a>, <a href="https://twitter.com/cocartapi" rel="nofollow ugc">X/Twitter</a>, <a href="https://www.instagram.com/cocartheadless/" rel="nofollow ugc">Instagram</a> and <a href="https://github.com/co-cart/co-cart" rel="nofollow ugc">GitHub</a></li>
</ul>
<h4>💯 Credits</h4>
This plugin is developed and maintained by <a href="https://twitter.com/sebd86" rel="nofollow ugc">Sébastien Dumont</a>. 
Founder of <a href="https://twitter.com/cocartheadless" rel="nofollow ugc">CoCart Headless, LLC</a>.

HeadlessKey – JWT Auth vs CoCart JWT Authentication