> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jwtauth.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)

<CardGroup cols={2}>
  <Card title="Structure" icon="layer-group">
    JWTs consist of three parts: Header, Payload, and Signature, each base64-encoded and separated by dots
  </Card>

  <Card title="Stateless" icon="cloud">
    Tokens carry all necessary information, reducing database queries and improving performance
  </Card>

  <Card title="Secure" icon="shield-halved">
    Digital signatures ensure token integrity and authenticity using cryptographic algorithms
  </Card>

  <Card title="Flexible" icon="puzzle-piece">
    Can include custom claims for additional user data or permissions
  </Card>
</CardGroup>

<Note>
  JWT Auth Pro uses [Firebase PHP-JWT](https://github.com/firebase/php-jwt) version 6.11.0 (latest version at the time of writing) for JWT handling, ensuring robust and secure token management.
</Note>

## 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:

<Steps>
  <Step title="Creation">
    Tokens are generated upon successful authentication with user credentials
  </Step>

  <Step title="Validation">
    Each API request validates the token's signature, expiration, and claims
  </Step>

  <Step title="Refresh">
    Access tokens are renewed using refresh tokens before expiration
  </Step>

  <Step title="Revocation">
    Tokens can be invalidated for security events or user actions
  </Step>
</Steps>

## Security Concepts

<CardGroup cols={2}>
  <Card title="Token Families" icon="diagram-project">
    Groups of related tokens that help prevent refresh token reuse and rotation attacks
  </Card>

  <Card title="Rate Limiting" icon="gauge-high">
    Prevents brute force attacks by limiting authentication attempts
  </Card>

  <Card title="Token Blacklisting" icon="ban">
    Maintains a list of revoked tokens for additional security and logging
  </Card>

  <Card title="Automatic Revocation" icon="rotate">
    Invalidates tokens on security-critical user actions, like password changes, email changes, and more.
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="Request Tracking">
    Each request is tracked based on the client's IP address
  </Step>

  <Step title="Window Management">
    Requests are counted within a configurable time window (default: 1 minute)
  </Step>

  <Step title="Limit Enforcement">
    When limits are exceeded (default: 60 requests per minute per IP), requests are blocked with a 429 (Too Many Requests) response
  </Step>

  <Step title="Reset Period">
    After the time window expires, the request count resets automatically
  </Step>
</Steps>

### Rate Limit Headers

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

<ResponseField name="X-RateLimit-Limit" type="integer">
  Maximum number of requests allowed in the current time window
</ResponseField>

<ResponseField name="X-RateLimit-Remaining" type="integer">
  Number of requests remaining in the current time window
</ResponseField>

<ResponseField name="X-RateLimit-Reset" type="timestamp">
  Unix timestamp when the current time window expires
</ResponseField>

<ResponseField name="Retry-After" type="integer">
  Seconds to wait before making another request (only present when rate limited)
</ResponseField>

### 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

<Note>
  All rate limits are configurable through the WordPress admin interface or using filters. See the [Configuration](/wordpress/configuration#rate-limiting) documentation for more details.
</Note>