Core Concepts
JSON Web Tokens are an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. In WordPress REST API authentication:
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:
Creation
Tokens are generated upon successful authentication with user credentials
Validation
Each API request validates the token’s signature, expiration, and claims
Refresh
Access tokens are renewed using refresh tokens before expiration
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
Request Tracking
Each request is tracked based on the client’s IP address
Window Management
Requests are counted within a configurable time window (default: 1 minute)
Limit Enforcement
When limits are exceeded (default: 60 requests per minute per IP), requests are blocked with a 429 (Too Many Requests) response
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:
Maximum number of requests allowed in the current time window
Number of requests remaining in the current time window
Unix timestamp when the current time window expires
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.