How to Set Up JWT Authentication for the WordPress REST API (Step-by-Step Guide)

Robert Halley

Why JWT Authentication Matters for the WordPress REST API

If you are building headless WordPress applications, mobile apps, or any external system that communicates with WordPress, you need a secure way to authenticate API requests. Sending usernames and passwords with every request is risky and inefficient. That is exactly where JWT authentication for the WordPress REST API comes in.

JSON Web Tokens (JWT) let you authenticate once, receive a signed token, and then use that token for all subsequent API requests. It is stateless, lightweight, and widely supported across programming languages and frameworks.

In this guide, we will walk through the complete process of setting up JWT authentication for the WordPress REST API, from plugin installation and configuration to generating tokens and testing authenticated requests with Postman. We will also cover real code examples and the most common pitfalls that trip up developers during setup.

What Is JWT and How Does It Work with WordPress?

A JSON Web Token is a compact, URL-safe string made up of three parts separated by dots:

  1. Header – Contains the token type (JWT) and the signing algorithm (e.g., HS256).
  2. Payload – Contains claims such as the user ID, issued-at time, and expiration time.
  3. Signature – A cryptographic hash that verifies the token has not been tampered with.

When a user sends valid credentials to your WordPress site, the JWT plugin generates a signed token. The client stores this token and includes it in the Authorization header of every subsequent API request. WordPress then validates the token and processes the request as that authenticated user.

Traditional Auth JWT Auth
Sends credentials with every request Sends credentials once, then uses a token
Server must verify credentials each time Server only validates the token signature
Requires session storage on server Stateless – no session storage needed
Higher risk of credential exposure Credentials are only transmitted once

Prerequisites Before You Start

Before jumping into the setup, make sure you have the following in place:

  • A working WordPress installation (version 5.6 or higher recommended)
  • Admin access to the WordPress dashboard
  • FTP or file manager access to edit wp-config.php and .htaccess
  • Postman (or a similar API testing tool) installed on your computer
  • HTTPS enabled on your site (strongly recommended for production)
  • The WordPress REST API accessible (it is enabled by default on modern WordPress installs)

You can quickly verify that the REST API is working by visiting https://yourdomain.com/wp-json/wp/v2/posts in your browser. If you see a JSON response with your posts, you are good to go.

Step 1: Install the JWT Authentication Plugin

The most widely used plugin for this purpose is JWT Authentication for WP REST API by Enrique Chavez, available on the WordPress.org plugin repository. There is also a premium version at jwtauth.pro with additional features like token revocation.

Installation via WordPress Dashboard

  1. Log in to your WordPress admin panel.
  2. Go to Plugins > Add New.
  3. Search for JWT Authentication for WP REST API.
  4. Click Install Now and then Activate.

Installation via Composer (for developers)

If you manage your WordPress dependencies with Composer, you can also install the plugin from the GitHub repository:

composer require developer-name/jwt-auth

Important: Do not skip the configuration steps below. Simply activating the plugin will not enable JWT authentication. You need to edit two critical files first.

Step 2: Configure the Secret Key in wp-config.php

The JWT plugin needs a secret key to sign and verify tokens. This key must be unique, long, and kept private.

Open your wp-config.php file (located in the root of your WordPress installation) and add the following lines before the line that says /* That's all, stop editing! */:

define('JWT_AUTH_SECRET_KEY', 'your-unique-secret-key-here');
define('JWT_AUTH_CORS_ENABLE', true);

How to Generate a Strong Secret Key

You can use the WordPress secret key generator to create a strong, random string. Copy one of the generated keys and paste it as the value for JWT_AUTH_SECRET_KEY.

Example:

define('JWT_AUTH_SECRET_KEY', 'dK8^hG!2mNpQrS5vWxYz#AcEfHjLnPsUwZbDgIkMoRtVyBaCeGiKmOpQrTvXz');

What Does JWT_AUTH_CORS_ENABLE Do?

Setting JWT_AUTH_CORS_ENABLE to true modifies the WordPress headers to allow Cross-Origin Resource Sharing. This is essential if your frontend application runs on a different domain or port than your WordPress backend (which is the case with most headless setups, React apps, or mobile applications).

Step 3: Enable the HTTP Authorization Header

This is the step that causes the most confusion. Many servers (especially shared hosting environments running Apache) strip the Authorization header before WordPress can read it. Without this header, JWT authentication will silently fail.

For Apache Servers

Open your .htaccess file in the WordPress root directory and add the following lines before the # BEGIN WordPress block:

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

Alternatively, if the above does not work on your hosting provider, try this variation:

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

For Nginx Servers

Add the following directive inside your server block in the Nginx configuration file:

location / {
    try_files $uri $uri/ /index.php?$args;
}

# Pass the Authorization header to PHP
fastcgi_param HTTP_AUTHORIZATION $http_authorization;

After making changes, restart Nginx:

sudo systemctl restart nginx

Quick Check

After configuring these settings, you can verify everything is working by visiting:

https://yourdomain.com/wp-json/jwt-auth/v1

If you see a JSON response from the JWT plugin namespace, the basic configuration is in place.

Step 4: Generate a JWT Token

Now that the plugin is installed and configured, you can generate your first token by sending a POST request to the token endpoint.

Token Endpoint

POST https://yourdomain.com/wp-json/jwt-auth/v1/token

Request Body (JSON)

{
  "username": "your_wordpress_username",
  "password": "your_wordpress_password"
}

Successful Response

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3lvdXJkb21haW4uY29tIiwiaWF0IjoxNzEyNTY0MzI2LCJuYmYiOjE3MTI1NjQzMjYsImV4cCI6MTcxMzE2OTEyNiwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiMSJ9fX0.abc123",
  "user_email": "[email protected]",
  "user_nicename": "admin",
  "user_display_name": "Admin"
}

Save this token. You will use it in the Authorization header for all authenticated requests.

Failed Response (Invalid Credentials)

{
  "code": "[jwt_auth] incorrect_password",
  "message": "The password you entered for the username admin is incorrect.",
  "data": {
    "status": 403
  }
}

Step 5: Validate the Token

You can verify that a token is still valid by sending a POST request to the validate endpoint:

POST https://yourdomain.com/wp-json/jwt-auth/v1/token/validate

Include the token in the Authorization header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Successful Validation Response

{
  "code": "jwt_auth_valid_token",
  "data": {
    "status": 200
  }
}

Step 6: Test Authenticated Requests with Postman

Let us put it all together with a practical Postman walkthrough.

6.1 Generate the Token in Postman

  1. Open Postman and create a new request.
  2. Set the method to POST.
  3. Enter the URL: https://yourdomain.com/wp-json/jwt-auth/v1/token
  4. Go to the Body tab, select raw, and choose JSON from the dropdown.
  5. Paste the following: 
    {
  "username": "admin",
  "password": "your_password"
}
  6. Click Send.
  7. Copy the token value from the response.

6.2 Create a Post Using the Token

  1. Create a new request in Postman.
  2. Set the method to POST.
  3. Enter the URL: https://yourdomain.com/wp-json/wp/v2/posts
  4. Go to the Headers tab and add:
    Key Value
    Authorization Bearer YOUR_TOKEN_HERE
    Content-Type application/json
  5. Go to the Body tab, select raw and JSON, then paste: 
    {
  "title": "My First JWT Authenticated Post",
  "content": "This post was created via the WordPress REST API using JWT authentication.",
  "status": "draft"
}
  6. Click Send.

If everything is configured correctly, you will receive a 201 Created response with the full post object. Check your WordPress dashboard and you will see the new draft post.

6.3 Retrieve Protected Data

Some REST API endpoints return different data depending on whether the request is authenticated. For example, fetching user data:

GET https://yourdomain.com/wp-json/wp/v2/users/me
Authorization: Bearer YOUR_TOKEN_HERE

This returns the full profile of the authenticated user, including email and capabilities that are hidden from unauthenticated requests.

Step 7: Using JWT Authentication in Your Code

Here are practical code examples for integrating JWT authentication into your applications.

JavaScript (Fetch API)

// Step 1: Get the token
const response = await fetch('https://yourdomain.com/wp-json/jwt-auth/v1/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'admin',
    password: 'your_password',
  }),
});

const data = await response.json();
const token = data.token;

// Step 2: Use the token to create a post
const postResponse = await fetch('https://yourdomain.com/wp-json/wp/v2/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify({
    title: 'Created with JWT',
    content: 'This post was created via JavaScript fetch.',
    status: 'draft',
  }),
});

const post = await postResponse.json();
console.log('Post created:', post.id);

PHP (using wp_remote_post)

// Get the token
$auth_response = wp_remote_post('https://yourdomain.com/wp-json/jwt-auth/v1/token', array(
  'body' => json_encode(array(
    'username' => 'admin',
    'password' => 'your_password',
  )),
  'headers' => array(
    'Content-Type' => 'application/json',
  ),
));

$auth_body = json_decode(wp_remote_retrieve_body($auth_response));
$token = $auth_body->token;

// Create a post using the token
$post_response = wp_remote_post('https://yourdomain.com/wp-json/wp/v2/posts', array(
  'body' => json_encode(array(
    'title'   => 'Created with PHP',
    'content' => 'This post was created using wp_remote_post with JWT.',
    'status'  => 'draft',
  )),
  'headers' => array(
    'Content-Type'  => 'application/json',
    'Authorization' => 'Bearer ' . $token,
  ),
));

Python (using requests)

import requests

# Get the token
auth_url = 'https://yourdomain.com/wp-json/jwt-auth/v1/token'
auth_data = {
    'username': 'admin',
    'password': 'your_password'
}

auth_response = requests.post(auth_url, json=auth_data)
token = auth_response.json().get('token')

# Create a post
posts_url = 'https://yourdomain.com/wp-json/wp/v2/posts'
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}
post_data = {
    'title': 'Created with Python',
    'content': 'This post was created using Python requests with JWT.',
    'status': 'draft'
}

response = requests.post(posts_url, json=post_data, headers=headers)
print(response.json())

Common Pitfalls and How to Fix Them

Based on our experience helping clients at Pixel Perfect Portfolios and the most frequently reported issues in the WordPress community, here are the problems you are most likely to encounter.

Pitfall 1: “jwt_auth_bad_config” Error

Cause: The JWT_AUTH_SECRET_KEY is not defined in wp-config.php.

Fix: Add the define('JWT_AUTH_SECRET_KEY', '...') line to your wp-config.php as described in Step 2. Make sure it appears before the “stop editing” comment.

Pitfall 2: “jwt_auth_no_auth_header” Error

Cause: The server is stripping the Authorization header before it reaches PHP.

Fix: Add the .htaccess rewrite rules (Apache) or fastcgi_param directive (Nginx) from Step 3. This is the single most common issue developers face.

Pitfall 3: CORS Errors in the Browser Console

Cause: Cross-origin requests are being blocked because the server is not sending the correct CORS headers.

Fix: Ensure JWT_AUTH_CORS_ENABLE is set to true in wp-config.php. If this does not solve it, you may need to add custom CORS headers in your theme’s functions.php:

add_action('init', function() {
  header('Access-Control-Allow-Origin: *');
  header('Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE');
  header('Access-Control-Allow-Headers: Authorization, Content-Type');
  if ('OPTIONS' === $_SERVER['REQUEST_METHOD']) {
    status_header(200);
    exit();
  }
});

Note: In production, replace the wildcard * with your actual frontend domain for better security.

Pitfall 4: Token Expired

Cause: JWT tokens have an expiration time. The default is typically 7 days.

Fix: You can extend the token expiration by adding a filter in your theme’s functions.php:

add_filter('jwt_auth_expire', function() {
  return time() + (DAY_IN_SECONDS * 30); // 30 days
});

For production applications, implement a token refresh mechanism rather than setting extremely long expiration times.

Pitfall 5: Plugin Conflicts

Cause: Security plugins (like Wordfence or iThemes Security) may block REST API requests or interfere with the Authorization header.

Fix: Whitelist the JWT endpoints in your security plugin settings, or temporarily disable other plugins to isolate the conflict.

Full Troubleshooting Reference Table

Error Message Likely Cause Solution
jwt_auth_bad_config Missing secret key Add JWT_AUTH_SECRET_KEY to wp-config.php
jwt_auth_no_auth_header Authorization header stripped Update .htaccess or Nginx config
jwt_auth_invalid_token Token is malformed or corrupted Generate a new token
jwt_auth_expired_token Token has expired Request a new token or extend expiration
rest_forbidden User lacks permissions Ensure user has the correct WordPress role
CORS error in browser Cross-origin not allowed Enable JWT_AUTH_CORS_ENABLE or add custom headers

Security Best Practices for JWT in WordPress

JWT authentication is powerful, but you need to follow security best practices to keep your site safe.

  • Always use HTTPS. JWT tokens are transmitted in plain text in the header. Without HTTPS, anyone on the network can intercept them.
  • Keep your secret key truly secret. Never commit wp-config.php to a public repository or share the secret key with anyone.
  • Set reasonable expiration times. Do not set tokens to last forever. Use short-lived tokens with a refresh mechanism.
  • Use dedicated API users. Create a WordPress user specifically for API access with only the permissions it needs. Avoid using admin accounts for API integrations.
  • Store tokens securely on the client side. In browser applications, use httpOnly cookies when possible instead of localStorage to reduce XSS attack vectors.
  • Monitor API usage. Use logging plugins or server logs to track unusual API activity.
  • Rotate your secret key periodically. This invalidates all existing tokens and forces re-authentication.

JWT Authentication Plugin Comparison

There are several JWT plugins available for WordPress. Here is a quick comparison to help you choose:

Plugin Free Token Revocation Refresh Tokens Best For
JWT Authentication for WP REST API (Enrique Chavez) Yes No No Simple projects and learning
JWT Auth Pro (jwtauth.pro) No Yes Yes Production applications
miniOrange JWT Authentication Freemium Yes Yes Enterprise with multiple auth methods

For most developers getting started with JWT authentication for the WordPress REST API, the free plugin by Enrique Chavez is the best starting point. If you need token revocation and refresh tokens for a production app, consider upgrading to JWT Auth Pro.

Complete Setup Checklist

Use this checklist to make sure you have not missed any steps:

  • ☐ WordPress REST API is accessible (/wp-json/wp/v2/posts returns data)
  • ☐ JWT Authentication plugin is installed and activated
  • ☐ JWT_AUTH_SECRET_KEY is defined in wp-config.php
  • ☐ JWT_AUTH_CORS_ENABLE is set to true (if needed)
  • ☐ .htaccess or Nginx config passes the Authorization header
  • ☐ Token generation endpoint returns a valid token
  • ☐ Token validation endpoint confirms the token is valid
  • ☐ Authenticated requests to /wp/v2/posts work in Postman
  • ☐ HTTPS is enabled on the site

Wrapping Up

Setting up JWT authentication for the WordPress REST API is not complicated once you understand the moving parts. The biggest hurdle for most developers is not the plugin itself but the server configuration, specifically making sure the Authorization header reaches PHP.

To recap the key steps:

  1. Install and activate the JWT Authentication plugin.
  2. Add the secret key and CORS setting to wp-config.php.
  3. Configure your server to pass the Authorization header.
  4. Generate tokens by posting credentials to the token endpoint.
  5. Include the token as a Bearer token in the Authorization header for all authenticated API requests.

With JWT authentication properly configured, you can build secure headless WordPress applications, connect mobile apps to your WordPress backend, and create powerful integrations that go far beyond what the standard WordPress admin interface offers.

If you are building a headless WordPress site or need help with WordPress REST API integrations, get in touch with our team at Pixel Perfect Portfolios. We specialize in custom WordPress development and API-driven architectures.

Frequently Asked Questions

Is JWT authentication secure for the WordPress REST API?

Yes, JWT authentication is secure when implemented correctly. The token is signed with a secret key, making it tamper-proof. However, you must use HTTPS to prevent token interception during transmission. Never expose your secret key publicly.

Can I use JWT authentication without a plugin?

Technically, yes. You can write custom code to handle JWT token generation and validation using PHP libraries like firebase/php-jwt. However, for most WordPress projects, using a well-maintained plugin is faster, safer, and easier to maintain.

How long does a JWT token last?

The default expiration for most WordPress JWT plugins is 7 days. You can customize this using the jwt_auth_expire filter in your theme’s functions.php file. For security-sensitive applications, shorter expiration times (such as 1 hour) combined with a refresh token mechanism are recommended.

Why am I getting a “jwt_auth_no_auth_header” error?

This almost always means your web server is stripping the Authorization header before it reaches WordPress. You need to add specific rewrite rules to your .htaccess file (Apache) or pass the header explicitly in your Nginx configuration. See Step 3 of this guide for the exact code.

Can I use JWT authentication with WooCommerce REST API?

WooCommerce has its own authentication system using consumer keys and secrets. While you can technically layer JWT on top, for WooCommerce-specific endpoints it is generally better to use the built-in WooCommerce REST API authentication. JWT is ideal for the core WordPress REST API endpoints.

Does JWT authentication work with WordPress multisite?

Yes, JWT authentication works with WordPress multisite. You need to define the JWT_AUTH_SECRET_KEY in the main wp-config.php, and the plugin should be network activated. Each subsite will use the same secret key for token generation and validation.

What happens if my secret key is compromised?

If your secret key is compromised, an attacker could forge valid tokens for any user. Immediately change the JWT_AUTH_SECRET_KEY value in wp-config.php. This will instantly invalidate all existing tokens, forcing all users and applications to re-authenticate.

Leave a Comment

Reach out to discuss what we can do for your business

Contact

3358 Frum Street

Nashville, TN 37201

USA

Our Privacy Policy Our Terms of Service Contact Us

©2022 Pixel Perfect Portfolios Designs. All Rights Reserved.