Throttling and the switch
Register the API's routes through the package:
// routes/api.php
use Illuminate\Support\Facades\Route;
use Pushery\SanctumHardening\SanctumHardening;
SanctumHardening::routes(function () {
Route::get('/orders', fn () => ['orders' => []]);
});
The routes are registered under routes.prefix, api by default, behind routes.middleware,
api and auth:sanctum by default, and behind the package's limiter. routes.middleware takes a
list or a single middleware as a string. A setting that names none, an empty list for instance,
keeps api and auth:sanctum, so the routes never run without the token guard by accident.
The package's limiter is a named rate limiter, sanctum-hardening, registered with Laravel's
RateLimiter::for(). throttle.limiter gives it another name where the application already has a
limiter called that. A route registered outside SanctumHardening::routes() shares the same limits
behind throttle:sanctum-hardening, or throttle: and the name throttle.limiter gives: its
requests count against the same token and the same user, and a request nobody is signed in for is
counted by its address.
Two stages
Each token has its own limit, throttle.per_token requests a minute, and each user has one over all
of their tokens, throttle.per_user. Without the second, a user gets past every limit of a token by
minting another one. A request over either is answered with 429 as a problem document
(RFC 9457), with the Retry-After header the limiter computed:
{
"type": "about:blank",
"title": "Too Many Requests",
"status": 429,
"detail": "Too many requests. Another one can be sent once the time in the Retry-After header has passed.",
"instance": "/api/orders"
}
A request authenticated by the session rather than a token counts as one token of its user. A request nobody is signed in for is counted by its address, kept as a keyed hash, because a rate limiter's key is a cache key and error trackers record cache keys.
The switch
SANCTUM_HARDENING_ENABLED=false switches the API off. SanctumHardening::routes() then
registers nothing, so the routes do not exist: a request meets no 403 from a route that refuses
but the 404 of a route that is not there, and route:list names none. Minting is not affected.
The last use of a token
Sanctum writes last_used_at on every request a token makes, so a busy token turns each request
into a write on the same row. The package lets that write through once every last_used_at.every
seconds, a minute by default. A save of a token that changes anything else goes through as it is.
The requests a token made
Every request a token makes through SanctumHardening::routes() is recorded once the answer is
sent: the route's name, or its URI pattern where it has none, the method, the status and the time.
The address with its values and the body are never kept, so nothing a person sent is stored. The
same token, route, method and status are written at most once every usage.every seconds, a minute
by default, and sanctum-hardening:prune-uses deletes the uses older than usage.keep_days days,
30 by default. A route of the application's own behind auth:sanctum is recorded as well with the
middleware Pushery\SanctumHardening\Http\RecordsTokenUse.
use Pushery\SanctumHardening\Tokens\TokenUses;
$uses = app(TokenUses::class);
$uses->latest($token, 10); // the newest first
$uses->usedBetween($token, now()->subWeek(), now()); // whether it was used in the week
The screen shows the latest requests of each token.