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.

Key Features

Standard JWT Authentication: Secure user authentication using industry-standard RFC 7519 tokens.
Multiple Algorithms: Support for HS256, RS256, and ES256 signing algorithms.
Comprehensive Endpoints: Ready-to-use endpoints for Login, Register, Token Refresh, and Password Management.
Single Sign-On (SSO): Connect multiple sites with a secure, headers-based SSO exchange mechanism.
Role-Based Access Control (RBAC): Configure public or authenticated access for every endpoint.
Brute Force Protection: Protects against attacks by locking users/IPs after failed attempts.
Activity Logs: Detailed audit trail of all authentication events, including IP and device data.
Security Webhooks: Real-time JSON events sent to your external services for monitoring key actions.
Device Limits: Restrict the number of active devices/sessions per user.
Developer Friendly: Extensive hooks and filters for deep customization.

Configuration

Secret Key

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 wp-config.php:

define('headlesskey_SECRET_KEY', 'your-long-random-secure-string');

You can generate a strong salt here: WordPress Salt Generator

CORS Support

Cross-Origin Resource Sharing (CORS) is enabled by default to allow frontend applications to connect. To disable or customize it via constant:

define('headlesskey_CORS', true); // or false to disable

REST API Namespace

By default, endpoints are under wp-json/wpauthapi/v1. You can customize this namespace:

define('headlesskey_REST_NAMESPACE', 'my-custom-auth');
define('headlesskey_REST_VERSION', 'v2');<h3>Endpoints</h3>

The plugin adds the following endpoints under the /wp-json/headlesskey/v1 namespace:

Endpoint
HTTP Verb
Description

/token
POST
Login: Exchange username/password for a JWT.

/token/validate
POST
Validate: Check if a token validity.

/token/refresh
POST
Refresh: Exchange a valid token for a new one (rotation).

/token/revoke
POST
Logout: Invalidate a specific token.

/register
POST
Register: Create a new user account.

/login
POST
Profile: Login and get full user profile data in one request.

/forgot-password
POST
Recover: Request a password reset via Link or OTP.

/reset-password
POST
Reset: Set a new password using a token or OTP.

/change-password
POST
Update: Change password for authenticated user.

/sso/exchange
POST
SSO: Exchange a remote site token for a local session.

1. Login (Generate Token)

Endpoint: POST /wp-json/headlesskey/v1/token
Description: Authenticate a user and generate a JWT token.

Request:
json { "username": "admin", "password": "secret-password" }

Response:
json { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "expiration": "2023-10-27T10:00:00+00:00", "expires_in": 3600, "user": { "ID": 1, "user_login": "admin", "user_email": "[email protected]", "display_name": "Administrator", "roles": ["administrator"] }, "refreshable": true, "jti": "545086b9-450f-488b-a70d-3047d14d1101" }

2. Validate Token

Endpoint: POST /wp-json/headlesskey/v1/token/validate
Description: Validate if an existing token is valid.

Request:
json { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }

Response:
json { "valid": true, "data": { "iss": "https://example.com", "iat": 1698393600, "exp": 1698397200, "data": { "ID": 1, "user_login": "admin" } } }

3. Refresh Token

Endpoint: POST /wp-json/headlesskey/v1/token/refresh
Description: Rotate an expiring token for a fresh one.

Request:
json { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }

Response:
json { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.new...", "expiration": "2023-10-27T11:00:00+00:00", "user": { "ID": 1, "user_login": "admin" }, "jti": "new-uuid-v4" }

4. Revoke Token (Logout)

Endpoint: POST /wp-json/headlesskey/v1/token/revoke
Description: Invalidate a token immediately.

Request:
json { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." }

Response:
json { "message": "Token revoked successfully." }

5. Register User

Endpoint: POST /wp-json/headlesskey/v1/register
Description: Create a new user account.

Request:
json { "username": "johndoe", "email": "[email protected]", "password": "secure-password", "name": "John Doe" }

Response:
json { "user_id": 45, "user": { "ID": 45, "user_login": "johndoe", "user_email": "[email protected]", "display_name": "John Doe", "roles": ["subscriber"] }, "token_response": { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...", "expiration": "2023-10-27T10:00:00+00:00" } }

6. User Profile (Login Extended)

Endpoint: POST /wp-json/headlesskey/v1/login
Description: Alternative login endpoint that returns cleaner profile structure.

Request:
json { "username": "admin", "password": "secret-password" }

Response:
json { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "expiration": "2023-10-27T10:00:00+00:00", "user": { "ID": 1, "user_login": "admin", "user_email": "[email protected]", "display_name": "Administrator", "roles": ["administrator"] } }

7. Forgot Password

Endpoint: POST /wp-json/headlesskey/v1/forgot-password
Description: Initiate password recovery. Note: delivery can be link or otp.

Request:
json { "login": "[email protected]", "delivery": "link" }

Response:
json { "message": "Password reset email sent." }

8. Reset Password

Endpoint: POST /wp-json/headlesskey/v1/reset-password
Description: Reset password using the token sent via email or OTP.

Request (Link method):
json { "login": "[email protected]", "password": "new-secure-password", "token": "generated-reset-key" }

Response:
json { "message": "Password updated successfully." }

9. Change Password

Endpoint: POST /wp-json/headlesskey/v1/change-password
Description: Change password for currently authenticated user. Requires Authorization header.

Headers:
Authorization: Bearer

Request:
json { "current_password": "old-password", "new_password": "new-secure-password" }

Response:
json { "message": "Password changed successfully. Please login again." }

10. SSO Token Exchange

Endpoint: POST /wp-json/headlesskey/v1/sso/exchange
Description: Securely exchange a token from a connected remote site for a local authentication session. This powers the distributed Single Sign-On network.

Request:
json { "site_key": "remote-site-id", "token": "remote-jwt-token", "signature": "hmac-sha256-signature" }

Response:
Returns a standard Login response (Token + User Data) if the signature is valid.