Title: HeadlessKey – JWT Auth
Author: Hidayat Mahetar
Published: <strong>2026 年 2 月 8 日</strong>
Last modified: 2026 年 2 月 8 日

---

搜尋外掛

![](https://ps.w.org/headlesskey-jwt-auth/assets/banner-772x250.png?rev=3456339)

![](https://ps.w.org/headlesskey-jwt-auth/assets/icon.svg?rev=3456339)

# HeadlessKey – JWT Auth

 由 [Hidayat Mahetar](https://profiles.wordpress.org/hidayatsafewp/) 開發

[下載](https://downloads.wordpress.org/plugin/headlesskey-jwt-auth.1.0.0.zip)

 * [詳細資料](https://tw.wordpress.org/plugins/headlesskey-jwt-auth/#description)
 * [使用者評論](https://tw.wordpress.org/plugins/headlesskey-jwt-auth/#reviews)
 * [開發資訊](https://tw.wordpress.org/plugins/headlesskey-jwt-auth/#developers)

 [技術支援](https://wordpress.org/support/plugin/headlesskey-jwt-auth/)

## 外掛說明

**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](https://api.wordpress.org/secret-key/1.1/salt/)

### 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": "admin@example.com", "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": "john@example.com", "password":"
secure-password", "name": "John Doe" }

**Response:**
 `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" } }

### 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":"
admin@example.com", "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": "admin@example.com", "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": "admin@example.com", "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.

## 螢幕擷圖

[⌊General Settings - Configure Token Expiration and Security Policy.⌉⌊General Settings-
Configure Token Expiration and Security Policy.⌉[

General Settings – Configure Token Expiration and Security Policy.

[⌊Algorithms - Choose between HS256, RS256, and ES256.⌉⌊Algorithms - Choose between
HS256, RS256, and ES256.⌉[

Algorithms – Choose between HS256, RS256, and ES256.

[⌊Logs - View recent authentication activity.⌉⌊Logs - View recent authentication
activity.⌉[

Logs – View recent authentication activity.

## 適用於區塊編輯器

這個外掛提供 1 個可供 Gutenberg/區塊編輯器使用的區塊。

 *   Demo Block Demo block scaffolded with HeadlessKey.

## 常見問題集

### How do I generate a JWT Secret?

The plugin automatically generates a strong secret key upon activation. You can 
find it in the plugin settings. For better security, you can define `headlesskey_SECRET_KEY`
in your `wp-config.php` file.

### Can I use this with Next.js or other frontend frameworks?

Yes! The plugin sends correct CORS headers and returns standard JSON responses, 
making it compatible with any frontend framework or language that supports HTTP 
requests.

### Does it support Public/Private keys?

Yes, you can configure RS256 or ES256 algorithms in the settings and provide your
PEM formatted keys for asymmetric signing.

## 使用者評論

這個外掛目前沒有任何使用者評論。

## 參與者及開發者

以下人員參與了開源軟體〈HeadlessKey – JWT Auth〉的開發相關工作。

參與者

 *   [ Hidayat Mahetar ](https://profiles.wordpress.org/hidayatsafewp/)

[將〈HeadlessKey – JWT Auth〉外掛本地化為台灣繁體中文版](https://translate.wordpress.org/projects/wp-plugins/headlesskey-jwt-auth)

### 對開發相關資訊感興趣？

任何人均可[瀏覽程式碼](https://plugins.trac.wordpress.org/browser/headlesskey-jwt-auth/)、
查看 [SVN 存放庫](https://plugins.svn.wordpress.org/headlesskey-jwt-auth/)，或透過
[RSS](https://plugins.trac.wordpress.org/log/headlesskey-jwt-auth/?limit=100&mode=stop_on_copy&format=rss)
訂閱[開發記錄](https://plugins.trac.wordpress.org/log/headlesskey-jwt-auth/)。

## 變更記錄

#### 1.0.0

 * **Initial Release**: Complete authentication suite with JWT, RBAC, SSO, and Security
   features.
 * **Security**: Added Brute Force protection, Device Limits, and Security Webhooks.
 * **API**: Full set of endpoints for Login, Register, Password Reset, and Token
   Management.

## 中繼資料

 *  版本 **1.0.0**
 *  最後更新 **5 個月前**
 *  啟用安裝數 **少於 10 次**
 *  WordPress 版本需求 ** 6.0 或更新版本 **
 *  已測試相容的 WordPress 版本 **6.9.4**
 *  PHP 版本需求 ** 8.0 或更新版本 **
 *  語言
 * [English (US)](https://wordpress.org/plugins/headlesskey-jwt-auth/)
 * 標籤:
 * [authentication](https://tw.wordpress.org/plugins/tags/authentication/)[headless](https://tw.wordpress.org/plugins/tags/headless/)
   [jwt](https://tw.wordpress.org/plugins/tags/jwt/)[rest-api](https://tw.wordpress.org/plugins/tags/rest-api/)
   [security](https://tw.wordpress.org/plugins/tags/security/)
 *  [進階檢視](https://tw.wordpress.org/plugins/headlesskey-jwt-auth/advanced/)

## 評分

這個項目尚無任何評論記錄。

[Your review](https://wordpress.org/support/plugin/headlesskey-jwt-auth/reviews/#new-post)

[查看全部使用者評論](https://wordpress.org/support/plugin/headlesskey-jwt-auth/reviews/)

## 參與者

 *   [ Hidayat Mahetar ](https://profiles.wordpress.org/hidayatsafewp/)

## 技術支援

使用者可在技術支援論壇提出意見反應或使用問題。

 [檢視技術支援論壇](https://wordpress.org/support/plugin/headlesskey-jwt-auth/)