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-Sourcewith the exact valuePN_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
- Client issues a request to
/api/.... - API Middleware group intercepts the request.
- RateLimiter checks for
X-Sync-Source: PN_Wordpress. - If present, no limit; otherwise, enforces 60/minute per user/IP.
- 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.