> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cocartapi.com/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>
</CardGroup>

<CardGroup cols={2}>
  <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>

## Token Types

CoCart JWT Authentication 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>

## Rate Limiting

Rate limiting is a security feature that helps protect your API from abuse by limiting the number of requests. For JWT, we force enable this feature when refreshing a client's token and validating within a specific time window.

<Info>
  Rate limiting is only supported if you have [CoCart Plus](https://cocartapi.com) installed.
</Info>

### 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">
    * For refresh token, limits are exceeded to `10` requests per minute per IP.
    * For validating token, limits are exceeded to `2` requests per minute per IP.

    Then 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

CoCart Plus 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:

* **Token Validation**: 10 requests per minute per token

* * Higher limit for API operations

* * Applies to protected endpoints

* **Token Refresh**: 2 requests per minute per refresh token

* * Moderate limit for token renewal

* * Prevents refresh token abuse