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.

Ahmed Hnewa

WordPress is a good content mangement system for building websites, but it will be better if you build like mobile apps, 
With the wordpress rest api you can create posts, edit posts, view posts, Users, Uploading Media etc… 
but the problem with the wordpress rest api it does not provide any authentication methods for third party application like mobile apps 
The Jwt Plugin on wordpress.org does provide that
and this plugin is just a addon for that plugin
So this plugin is useful if you don’t want to make another request to fetch user data like Id etc.. 
because you have to get the id of the user in ordet to get all data
It really simple plugin 
it writed with 50 lines of code, the size of the plugin is 3Kb
Note: This Is Plugin For 
<a href="https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api/" rel="ugc">JWT Authentication for WP REST API Plugin</a>
so if the jwt authentication plugin is not installed 
this plugin will not add the fields to it endpoints
and the fields will be added only if the token is getted successfully
Example request (before install the plugin): 
{ 
    “token”: “eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xOTIuMTY4LjAuMTgyIiwiaWF0IjoxNjE0MDg3NDQ2LCJuYmYiOjE2MTQwODc0NDYsImV4cCI6MTYxNDY5MjI0NiwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiMSJ9fX0.KeAUc7PiTne0_PThsSAWo1ruvl2Ocu-fbCn2jG7zkoE”, 
    “user_email”: “example@example.com”, 
    “user_nicename”: “admin”, 
    “user_display_name”: “admin” 
}
Example response (after install the plugin): 
{ 
    “token”: “eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xOTIuMTY4LjAuMTgyIiwiaWF0IjoxNjE0MDg2NjQyLCJuYmYiOjE2MTQwODY2NDIsImV4cCI6MTYxNDY5MTQ0MiwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiMSJ9fX0.nyDOICdQcZKbWZo2kQRp_eLBkuxjnK_rpxs-HJREyCg”, 
    “user_email”: “example@example.com”, 
    “user_nicename”: “admin”, 
    “user_display_name”: “admin”, 
    “user_id”: 1, 
    “user_login”: “admin”, 
    “user_first_name”: “sfd”, 
    “user_last_name”: “”, 
    “user_roles”: [ 
        “administrator” 
    ], 
    “user_role”: “administrator”, 
    “user_registered”: “2021-02-17 09:21:29”, 
    “user_url”: “http://localhost”, 
    “user_status”: “0”, 
    “user_avatar_url”: “https://secure.gravatar.com/avatar/22feea4605ac5b7163eac439b5241034?s=96&d=mm&r=g”, 
    “user_activation_key”: “” 
}
Of course you can add the code of this plugin to your Theme, 
but this is not recommened because when you change the theme or update it 
the changes will revert back, you can create child theme for that 
but instead you can just install this simple plugin
Don’t forget to setup (JwtAuthenticatonForWordpress)[https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api/]
<a href="https://github.com/ahmedhnewa/user-data-fields-jwt-plugin" rel="nofollow ugc">Github</a>
<h3>Can Add User Data Fields To Validate Token Endpoint ?</h3>
This plugin can also add user data fields to validate token endpoint,
Unfortunately, the jwt extension does not support using the filter for validate_token function, 
So You Will Need To Modify Some Codes Inside Jwt Plugin Codes 
Go To \wp-content\plugins\jwt-authentication-for-wp-rest-api\public\class-jwt-auth-public.php 
And At The End Of Function That Named validate_token 
In Line 302
Edit This Code 
From : 
/** If the output is true return an answer to the request to show it */ 
 return array( 
 ‘code’ => ‘jwt_auth_valid_token’, 
 ‘data’ => array( 
 ‘status’ => 200, 
 ), 
 ); 
To : 
$value = array( 
 ‘code’ => ‘jwt_auth_valid_token’, 
 ‘data’ => array( 
 ‘status’ => 200, 
 ) 
 ); 
 /** If the output is true return an answer to the request to show it */ 
 return apply_filters(‘jwt_auth_validate_token’, $value, $token);
Now you have done, 
the plugin should be able to add new values by adding a filter
Note : 
If you updated the jwt plugin, 
you should again edit the code because it will be removed
<h3>REQUIREMENTS</h3>
<a href="https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api/" rel="ugc">JWT Authentication for WP REST API Plugin</a>

User Data Fields For JWT Authentication

Good And Very Simple Plugin For Jwt Authentication

The JWT team should add a filter for validating requests too.

Well Self Usage Plugin

Wordpress is a good content mangement system for building websites, but it will be better if you build like mobile apps,

HeadlessKey – JWT Auth vs User Data Fields For JWT Authentication