Rate limiting and source trust

Security and compliance notes – Rate limiting and source trust

This section outlines how the platform enforces rate limits on API requests and codifies trusted sync sources to protect public endpoints while allowing internal integrations to bypass limits.

Purpose and Scope

  • Ensure public-facing API endpoints remain available and resistant to abuse.
  • Allow specific internal sync processes (e.g., WordPress syncs) to operate without hindrance.
  • Centralize rate-limiting logic and trusted-source configurations in one place.

Rate Limiting

The application applies a per-minute rate limit of 60 requests per user or IP address on all routes under the api middleware group. This prevents excessive use and helps maintain system stability.

🔢 Scope 🛑 Condition ⏱️ Limit
Public API clients No special header or other headers 60 requests/minute per user ID or IP
Trusted sync calls Header X-Sync-Source: PN_Wordpress present Unlimited (none)

Key points:

  • Rate limits reset every minute.
  • Authenticated users are tracked by their user ID; anonymous clients fall back to IP addresses.
  • Misbehaving clients receive HTTP 429 Too Many Requests responses.

Trusted Sync Sources

Some integrations, such as the PN_Wordpress synchronization routine, require unfettered access to API endpoints. To enable this safely:

  • Clients MUST include an HTTP header X-Sync-Source with the exact value PN_Wordpress.
  • Requests bearing this header bypass the standard rate limits (unlimited throughput).
  • All other requests without this header are subject to the 60/minute cap.

This source trust mechanism isolates internal data-sync operations from public usage patterns.


Implementation Details

Rate limiting and source trust are configured in RouteServiceProvider. The following excerpt demonstrates how Laravel’s RateLimiter facade is used:

// app/Providers/RouteServiceProvider.php

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;

public function boot(): void
{
    RateLimiter::for('api', function (Request $request) {
        // Bypass limits for WordPress sync
        if ($request->header('X-Sync-Source') === 'PN_Wordpress') {
            return Limit::none();
        }

        // Standard limit: 60 requests per minute per user or IP
        return Limit::perMinute(60)
            ->by($request->user()?->id ?: $request->ip());
    });

    $this->routes(function () {
        $this->mapApiRoutes();
        // ... other route mappings ...
    });
}

💡 The 'api' key passed to RateLimiter::for ties directly to the throttle:api middleware, ensuring this policy applies to all API routes.


Middleware Integration

To activate the throttle:api middleware globally, the application registers it at bootstrap. In bootstrap/app.php, you’ll find:

// bootstrap/app.php (excerpt)

$middleware->throttleApi();

This single line instructs Laravel to apply the above RateLimiter policy (named “api”) to every route in the api group, without manually adding throttle:api to each route file.


How It Works Together

flowchart TD
  Client -->|HTTP Request| API_Middleware
  API_Middleware -->|Reads X-Sync-Source| RateLimiter
  RateLimiter -->|Bypass if header matches| Controller
  RateLimiter -->|Limit 60/min otherwise| Controller
  Controller -->|Process Request| Response
  1. Client issues a request to /api/....
  2. API Middleware group intercepts the request.
  3. RateLimiter checks for X-Sync-Source: PN_Wordpress.
  4. If present, no limit; otherwise, enforces 60/minute per user/IP.
  5. Controller executes business logic and returns a response.

Best Practices & Compliance

  • Log rate-limit violations at WARN level to identify potential abuse.
  • Monitor sync-source usage to ensure no unauthorized clients are bypassing limits.
  • Rotate or restrict trusted-source header values if compromised.
  • Document header usage clearly for third-party integrations.
{
  "title": "Key Takeaway",
  "content": "All API requests must pass through a single, centralized rate-limiter with explicit bypass logic for trusted sync sources."
}

Ensuring a clear separation between public traffic and internal sync operations helps maintain security, availability, and compliance across the platform.