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.

Gaurav Sharma

Extends the WP REST API using JSON Web Tokens as an authentication method. 
GS JWT plugin provides to encode and decode JSON Web Tokens (JWT), conforming to RFC 7519.
GET OTP and send notification by mail or SMS service
Support and Requests please in Github: https://github.com/gauravin213/gs-jwt
<h3>REQUIREMENTS</h3>
<h3>PHP</h3>
Minimum PHP version: 5.3.0
<h3>PHP HTTP Authorization Header enable</h3>
Most of the shared hosting has disabled the HTTP Authorization Header by default.
To enable this option you’ll need to edit your .htaccess file adding the following
<pre><code>RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]
</code></pre>
<h4>WPENGINE</h4>
To enable this option you’ll need to edit your .htaccess file adding the following
<pre><code>SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
</code></pre>
<h4>CONFIGURATION</h4>
The JWT needs to Add constant in the wp-confige.php file
<pre><code>define( 'GS_WP_JWT_SECRET_KEY', 'your-top-secret-key' );
define( 'GS_WP_JWT_ALGO', 'HS256' );
define( 'GS_WP_JWT_EXPIRY', (60 * 60) ); //seconds * minuts
define( 'GS_WP_OTP_EXPIRY', 10); //minuts
</code></pre>
<h3>Namespace and Endpoints</h3>
When the plugin is activated, a new namespace is added
<pre><code>/gs-jwt/v1
</code></pre>
Also, two new endpoints are added to this namespace
Endpoint | HTTP Verb
/wp-json/gs-jwt/v1/login | POST
/wp-json/gs-jwt/v1/token/validate | POST
/wp-json/gs-jwt/v1/get-otp | POST
/wp-json/gs-jwt/v1/verify-otp | POST
/wp-json/gs-jwt/v1/register_user | POST
/wp-json/gs-jwt/v1/register_userbymobile | POST
<h3>USAGE</h3>
<ol>
<li>Get JSON web token</li>
</ol>
<h4>Request method:</h4>
<pre><code>POST /wp-json/gs-jwt/v1/login

Body{
 "username": "enter username",
 "password": "enter password"
}
</code></pre>
<h4>Reponse</h4>
<pre><code>{
 "data": {
 "id": "1",
 "user_login": "admin",
 "user_pass": null,
 "user_nicename": "admin",
 "user_email": "example@gmail.com",
 "user_url": "",
 "user_registered": "2020-08-11 07:35:37",
 "user_activation_key": "",
 "user_status": "0",
 "display_name": "admin",
 "roles": [
 "administrator"
 ],
 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xMjcuMC4wLjFcL3dvcmRwcmVzcyIsImlhdCI6MTY0MTk3MDIwNSwibmJmIjoxNjQxOTcwMjA1LCJleHAiOjE2NDE5NzM4MDUsImRhdGEiOnsidXNlciI6eyJpZCI6IjEifX19.gRF_aNsmhQ8kqXYdKbm6dIA7zTlhcCU-e_cpP9pQDyM"
 }
}
</code></pre>
<ol>
<li>Validate JSON web token</li>
</ol>
<h4>Request method:</h4>
<pre><code>POST /wp-json/gs-jwt/v1/token/validate

Make a POST request sending the Authorization header
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xMjcuMC4wLjFcL3dvcmRwcmVzcyIsImlhdCI6MTY0MTk3MDIwNSwibmJmIjoxNjQxOTcwMjA1LCJleHAiOjE2NDE5NzM4MDUsImRhdGEiOnsidXNlciI6eyJpZCI6IjEifX19.gRF_aNsmhQ8kqXYdKbm6dIA7zTlhcCU-e_cpP9pQDyM
</code></pre>
<h4>Reponse</h4>
<pre><code>{
 "code": "jwt_auth_valid_token",
 "data": {
 "status": 200
 }
}
</code></pre>
<ol>
<li>Get otp by billing mobile number</li>
</ol>
<h4>Request method:</h4>
<pre><code>POST /wp-json/gs-jwt/v1/get-otp

Body{
 "mobile": "enter mobile number"
}
</code></pre>
<h4>Reponse</h4>
<pre><code>{
 "data": {
 "otp": 249225,
 "message": "SUCCESS",
 "otp_use_staus": "0",
 "notification": {
 "mail_send_status": 0,
 "sms_send_status": 0
 }
 }
}
</code></pre>
<ol>
<li>Verify otp and mobile number to login </li>
</ol>
<h4>Request method:</h4>
<pre><code>POST /wp-json/gs-jwt/v1/verify-otp

Body{
 "otp": "enter otp",
 "mobile": "enter mobile number"
}
</code></pre>
<h4>Reponse</h4>
<pre><code>{
 "data": {
 "id": "1",
 "user_login": "admin",
 "user_pass": null,
 "user_nicename": "admin",
 "user_email": "example@gmail.com",
 "user_url": "",
 "user_registered": "2020-08-11 07:35:37",
 "user_activation_key": "",
 "user_status": "0",
 "display_name": "admin",
 "roles": [
 "administrator"
 ],
 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xMjcuMC4wLjFcL3dvcmRwcmVzcyIsImlhdCI6MTY0MTk3MDIwNSwibmJmIjoxNjQxOTcwMjA1LCJleHAiOjE2NDE5NzM4MDUsImRhdGEiOnsidXNlciI6eyJpZCI6IjEifX19.gRF_aNsmhQ8kqXYdKbm6dIA7zTlhcCU-e_cpP9pQDyM"
 }
}
</code></pre>
<ol>
<li>Register user</li>
</ol>
<h4>Request method:</h4>
<pre><code>POST /wp-json/gs-jwt/v1/register_user

Body{
 "username": "example",
 "password": "example@123",
 "email": "example@gmail.com",
 "mobile": "1122336699"
}
</code></pre>
<h4>Reponse</h4>
<pre><code>{
 "data": {
 "id": 29,
 "user_login": "example",
 "user_pass": null,
 "user_nicename": "example",
 "user_email": "example@gmail.com",
 "user_url": "",
 "user_registered": "2022-01-12 07:45:29",
 "user_activation_key": "",
 "user_status": "0",
 "display_name": "example",
 "roles": [
 "customer"
 ],
 "billing_phone": "1122336699"
 },
 "code": 200,
 "message": "Registration was Successful"
}
</code></pre>
<ol>
<li>Register user by mobile number</li>
</ol>
<h4>Request method:</h4>
<pre><code>POST /wp-json/gs-jwt/v1/register_userbymobile

Body{
 "mobile": "1122336699"
}
</code></pre>
<h4>Reponse</h4>
<pre><code>{
 "data": {
 "id": 32,
 "user_login": "1144556638",
 "user_nicename": "1144556638",
 "user_registered": "2022-01-13 06:29:30",
 "display_name": "1144556638",
 "roles": [
 "customer"
 ],
 "billing_phone": "1144556638"
 },
 "code": 200,
 "message": "Registration was Successful"
}
</code></pre>
<h4>Sample add SMS and email notification</h4>
<pre><code>/*
* Send notification 
* Default mail_send_status = 0, sms_send_status = 0
*/
function gs_wp_jwt_send_notification_fun( $data, $user_id, $otp, $mobile ) {

 //Write mail send code here
 $from = get_option('admin_email');
 $to = get_user_meta($user_id, 'billing_email', true);
 $subject = "OTP Verification";
 $message = "OTP number: {$opt} will expire in 10 min";
 $headers = "From: ".$from;
 $result = wp_mail( $to, $subject, $message, $headers);

 if ($result) { 

 $data['mail_send_status'] = 1;

 } //end mail send


 //Write sms send api code here
 /*if ($sms_send_status) { 

 $data['sms_send_status'] = 1;

 } //ens sms send*/

 return $data;
}
add_filter( 'gs_wp_jwt_send_notification', 'gs_wp_jwt_send_notification_fun', 10, 4 );
</code></pre>

GS JWT Authentication for WP REST API

Extends the WP REST API using JSON Web Tokens as an authentication method.

HeadlessKey – JWT Auth vs GS JWT Authentication for WP REST API