Simple JWT Auth – JWT Authentication for WP REST API

Built for developers — authenticate WordPress from React, Next.js, Vue, mobile apps, and any other external client. Configuration can live in the plugin settings or be overridden with wp-config.php constants.

• Support & questions: WordPress support forum
• Bug reports: GitHub issues tracker
• Source code: GitHub repository

Enable PHP HTTP Authorization Header

HTTP Authorization is the mechanism clients use to send credentials to a server — a special Authorization header in the HTTP request. Many shared hosts have it disabled by default.

Shared hosts

Add the following to your .htaccess file:

RewriteEngine on RewriteCond %{HTTP:Authorization} ^(.*) RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]

WP Engine

Add the following to your .htaccess file:

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

Configuration

Simple JWT Auth uses a Key-Encryption-Key (KEK) to encrypt and decrypt the JWT signing keys ( secret_key , private_key , and public_key ) at rest. Define it in wp-config.php with the SIMPLE_JWT_AUTH_ENCRYPT_KEY constant. The KEK must be exactly 32 characters long and must never be revealed.

define( 'SIMPLE_JWT_AUTH_ENCRYPT_KEY', 'your-32-char-encryption-key' );

Rotating the KEK invalidates the stored signing keys and requires re-entering them in the plugin settings (a simplejwt_kek_mismatch error is returned until then).

Signing keys via wp-config.php constants

Instead of storing signing keys in the database, define them directly in wp-config.php file. Constants take precedence over the plugin settings, and their values are used as-is (plaintext, not encrypted).

define( 'SIMPLE_JWT_AUTH_ALGORITHM', 'HS256' ); // HS256, HS384, HS512, RS256, RS384, RS512, ES256 or ES384. define( 'SIMPLE_JWT_AUTH_SECRET_KEY', 'your-secret-key' ); // Required for HS* algorithms (min 32 chars). define( 'SIMPLE_JWT_AUTH_PRIVATE_KEY', '-----BEGIN PRIVATE KEY-----...' ); // Required for RS*/ES* signing. define( 'SIMPLE_JWT_AUTH_PUBLIC_KEY', '-----BEGIN PUBLIC KEY-----...' ); // Required for RS*/ES* verification.

• SIMPLE_JWT_AUTH_ALGORITHM — overrides algorithm , the JWT signing algorithm.
• SIMPLE_JWT_AUTH_SECRET_KEY — overrides secret_key , used for symmetric (HS256/384/512) signing and verification.
• SIMPLE_JWT_AUTH_PRIVATE_KEY — overrides private_key , used for asymmetric (RSA/EC) signing.
• SIMPLE_JWT_AUTH_PUBLIC_KEY — overrides public_key , used for asymmetric (RSA/EC) verification.

When a constant is defined, the matching field on the Settings page is disabled and marked “Defined in wp-config.php”.

Enabling authentication

For a fresh install, authentication is disabled by default. Turn on Enable JWT in the plugin settings, choose an algorithm, and provide the required signing key(s) before issuing tokens.

REST Endpoints

The plugin registers the auth/v1 namespace with five endpoints:

• POST /wp-json/auth/v1/token — Authenticate credentials; return an access token and a refresh token.
• POST /wp-json/auth/v1/token/refresh — Rotate an access token (and refresh token) using a refresh token.
• POST /wp-json/auth/v1/token/revoke — Revoke a refresh token and its rotation family.
• POST /wp-json/auth/v1/token/validate — Validate an access token.
• GET /wp-json/auth/v1/me — Return the authenticated user’s profile.

Generate a token

Submit a POST request with username and password :

curl --location 'https://example.com/wp-json/auth/v1/token' \ --header 'Content-Type: application/json' \ --data-raw '{ "username": "wordpress_username", "password": "wordpress_password" }'

Success response:

{ "code": "simplejwt_auth_credential", "message": "Token created successfully", "data": { "status": 200, "id": "2", "email": "user@example.com", "nicename": "username", "display_name": "User Name", "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...", "token_expires_in": 900, "refresh_token": "opaque-refresh-token", "refresh_expires_in": 1209600 } }

Store the access token and refresh token in your application (a secure cookie, localStorage , or a wrapper such as localForage ). Then pass the access token as a Bearer header on every protected request:

Authorization: Bearer your-access-token

For example, creating a post with an access token:

curl --location 'https://example.com/wp-json/wp/v2/posts' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...' \ --data '{ "title": "Hello headless", "content": "Created through the REST API with JWT authentication.", "status": "publish" }'

Refresh a token

Access tokens are short-lived. When one expires, send the refresh token to /token/refresh (in the body or as a Bearer header) to rotate it and receive a new access token and refresh token:

curl --location 'https://example.com/wp-json/auth/v1/token/refresh' \ --header 'Content-Type: application/json' \ --data-raw '{ "refresh_token": "opaque-refresh-token" }'

The response has the same shape as the token response. Each rotation invalidates the previous refresh token.

Revoke a token

To invalidate a session, send the refresh token to /token/revoke :

curl --location 'https://example.com/wp-json/auth/v1/token/revoke' \ --header 'Content-Type: application/json' \ --data-raw '{ "refresh_token": "opaque-refresh-token" }'

Success response:

{ "code": "simplejwt_token_revoked", "message": "Token has been revoked", "data": { "status": 200 } }

Validate a token

Verify an access token with a POST request carrying the Bearer header:

curl --location --request POST 'https://example.com/wp-json/auth/v1/token/validate' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...'

Success response:

{ "code": "simplejwt_valid_token", "message": "Token is valid", "data": { "status": 200 } }

Current user

Get the authenticated user’s profile:

curl --location 'https://example.com/wp-json/auth/v1/me' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...'

Success response:

{ "code": "simplejwt_user", "message": "User data retrieved successfully", "data": { "status": 200, "id": 2, "email": "user@example.com", "nicename": "username", "display_name": "User Name", "roles": ["administrator"] } }

REST Errors

Every error returns a consistent envelope with a stable code , a message , and a data.status HTTP status. Common codes include:

• simplejwt_missing_credentials — Username or password is missing.
• simplejwt_invalid_username — The username is not registered on this site.
• simplejwt_incorrect_password — The password is incorrect.
• simplejwt_no_auth_header — The Authorization header is missing.
• simplejwt_bad_auth_header — The Authorization header is malformed.
• simplejwt_invalid_token — The access token is invalid (bad signature, malformed, or not yet valid).
• simplejwt_expired_token — The access or refresh token has expired.
• simplejwt_invalid_refresh_token — The refresh token is unknown or invalid.
• simplejwt_reused_refresh_token — A rotated refresh token was reused; the token family was revoked.
• simplejwt_revoked_token — The token has been revoked.
• simplejwt_bad_issuer — The token issuer does not match this server.
• simplejwt_unsupported_algorithm — The configured signing algorithm is unsupported.
• simplejwt_rate_limited — Too many requests; please try again later.
• simplejwt_bad_config — JWT authentication is not configured or is disabled.
• simplejwt_bad_encryption_key — The key-encryption-key is not configured.
• simplejwt_invalid_enckey_length — The key-encryption-key is not exactly 32 characters.
• simplejwt_kek_mismatch — The key-encryption-key was rotated; re-enter the signing keys.

Available Hooks

Simple JWT Auth is developer-friendly and exposes filter and action hooks to override its default behaviour.

simplejwt_cors_allow_headers (filter)

Modify the CORS Access-Control-Allow-Headers value. Default: Access-Control-Allow-Headers, Content-Type, Authorization .

add_filter( 'simplejwt_cors_allow_headers', function ( $headers ) { return $headers; } );

simplejwt_auth_iss (filter)

Change the token iss (issuer) claim. Default: get_bloginfo( 'url' ) .

add_filter( 'simplejwt_auth_iss', function ( $iss ) { return $iss; } );

simplejwt_not_before (filter)

Change the token nbf (not-before) claim. Def