​
JSON Web Tokens (JWT)

Structure

JWTs consist of three parts: Header, Payload, and Signature, each base64-encoded and separated by dots

Stateless

Tokens carry all necessary information, reducing database queries and improving performance

Secure

Digital signatures ensure token integrity and authenticity using cryptographic algorithms

Flexible

Can include custom claims for additional user data or permissions

JWT Auth Pro uses Firebase PHP-JWT version 6.11.0 (latest version at the time of writing) for JWT handling, ensuring robust and secure token management.

​
Token Types

JWT Auth Pro implements a dual-token system for enhanced security. The system uses two distinct types of tokens:

​
Access Tokens

Short-lived tokens used for API authentication. They:

  • Carry user identity and permissions
  • Are included in the Authorization header for API requests
  • Have configurable expiration times
  • Are validated on each request

​
Refresh Tokens

Long-lived tokens used to maintain user sessions. They:

  • Are used to obtain new access tokens
  • Are stored securely in the database
  • Implement secure token rotation
  • Help maintain persistent authentication

​
Token Lifecycle

Understanding how tokens are managed throughout their lifetime:

1

Creation

Tokens are generated upon successful authentication with user credentials

2

Validation

Each API request validates the token’s signature, expiration, and claims

3

Refresh

Access tokens are renewed using refresh tokens before expiration

4

Revocation

Tokens can be invalidated for security events or user actions

​
Security Concepts

Token Families

Groups of related tokens that help prevent refresh token reuse and rotation attacks

Rate Limiting

Prevents brute force attacks by limiting authentication attempts

Token Blacklisting

Maintains a list of revoked tokens for additional security and logging

Automatic Revocation

Invalidates tokens on security-critical user actions, like password changes, email changes, and more.

​
Rate Limiting

Rate limiting is a security feature that helps protect your API from abuse by limiting the number of requests a client can make within a specific time window.

​
How It Works

1

Request Tracking

Each request is tracked based on the client’s IP address

2

Window Management

Requests are counted within a configurable time window (default: 1 minute)

3

Limit Enforcement

When limits are exceeded (default: 60 requests per minute per IP), requests are blocked with a 429 (Too Many Requests) response

4

Reset Period

After the time window expires, the request count resets automatically

​
Rate Limit Headers

JWT Auth Pro includes standard rate limit headers in API responses:

​
X-RateLimit-Limit
integer

Maximum number of requests allowed in the current time window

​
X-RateLimit-Remaining
integer

Number of requests remaining in the current time window

​
X-RateLimit-Reset
timestamp

Unix timestamp when the current time window expires

​
Retry-After
integer

Seconds to wait before making another request (only present when rate limited)

​
Default Limits

Different endpoints have different rate limits to balance security and usability:

  • Authentication: 5 requests per minute per IP

    • Protects against brute force attacks
    • Applies to token generation endpoints

  • Token Validation: 60 requests per minute per token

    • Higher limit for API operations
    • Applies to protected endpoints

  • Token Refresh: 10 requests per minute per refresh token

    • Moderate limit for token renewal
    • Prevents refresh token abuse

All rate limits are configurable through the WordPress admin interface or using filters. See the Configuration documentation for more details.