Middleware Reference

Every HTTP middleware the package registers, what it does, where to apply it, what it returns on failure, and how to order it. All package middleware is registered automatically by AuthServiceProvider — you do not need to add anything to bootstrap/app.php. Just reference the alias on your routes.

All failure responses use the same JSON envelope as the rest of the package — { "success": false, "message": "...", "errors": {} } — resolved through your configured ResponseFormatterContract. Examples below show the default formatter's output.

v2.7+ additions (quick reference)

Three new middleware aliases were registered in v2.7.1. The alias cheat-sheet and per-middleware sections below do not yet list them. Quick reference:

The classes live at src/Http/Middleware/EnforceRequired2FA.php, src/Http/Middleware/RequireStepUpForApiTokenCreation.php, and src/Http/Middleware/AdminGate.php. Full per-flag behavior is documented in the root UPGRADING.md.

Table of Contents

• Alias cheat-sheet
• Built-in Laravel middleware the package depends on
• How the package mounts its own routes
• Authentication & identity
  • auth.device — DeviceFingerprint
  • auth.api-token — ApiTokenAuth
  • auth.no-refresh — RejectRefreshToken
• Account gating
  • auth.verified — RequireEmailVerified
  • auth.active — RequireActiveAccount
• Step-up / sensitive actions
  • auth.2fa — Require2FA
  • auth.step-up — RequireStepUp
• Feature & mode gating
  • auth.feature — FeatureFlag
  • auth.mode — AuthMode
  • auth.ratelimit — RateLimitAuth
• Internal / route-stack middleware
  • ConditionalCsrf
• Third-party (Spatie) aliases
  • role, permission, role_or_permission
• Recommended ordering
• Recipes

Alias cheat-sheet

Built-in Laravel middleware the package depends on

Some package middleware only works after a Laravel/Sanctum built-in has already run. These are framework middleware, not shipped by this package — but the package's routes require them, and so do yours if you reuse the package middleware on your own routes. The package already wires them into its own route groups; this section tells you which ones matter and why.

auth:sanctum — REQUIRED before most package middleware

Ships with: Laravel Sanctum (laravel/sanctum, a hard dependency of this package).

Why it's required. auth:sanctum is what actually authenticates the request — it resolves the bearer token or session cookie into $request->user(). Almost every package middleware downstream reads $request->user():

• auth.no-refresh inspects $request->user()?->currentAccessToken().
• auth.verified calls $user->hasVerifiedEmail().
• auth.active reads the user's account status.
• auth.2fa needs to know who to challenge.

If you put any of these on a route without auth:sanctum in front, $request->user() is null: auth.verified/auth.active silently pass through (they treat "no user" as "nothing to gate"), and auth.2fa returns 401 Unauthenticated. So: always list auth:sanctum first on protected routes.

// ✅ correct — sanctum authenticates, then package middleware gate
Route::middleware(['auth:sanctum', 'auth.verified', 'auth.2fa'])->group(/* … */);

// ❌ wrong — package middleware run with no authenticated user
Route::middleware(['auth.verified', 'auth.2fa'])->group(/* … */);

Route::middleware(['auth.device', 'throttle:api'])->group(function () {
    Route::post('login', ...)->middleware('auth.ratelimit:login');
    Route::post('2fa/challenge', ...)->middleware('auth.ratelimit:otp_verify');
    // …
});

Route::middleware(['auth:sanctum', 'auth.no-refresh', 'auth.verified', 'auth.device'])
    ->group(function () {
        Route::get('me', ...);
        Route::delete('trusted-devices/{id}', ...)->middleware('auth.2fa');
        // …
    });

• X-Device-Info — mobile apps send a structured device descriptor.

1. Reads the bearer token; rejects anything not starting with auth_at_.
2. Validates it via ApiTokenService (existence, not-revoked, not-expired).
3. Optionally checks one or more abilities passed as middleware parameters.

• auth.api-token — any valid token.

• auth.api-token:read — token must have the read ability.

• 401 — "API token required." (missing / wrong prefix), or the typed exception message (revoked, expired), or "Invalid API token." (unexpected error; details are logged, never leaked).

1. Recent 2FA stamp? If the current session/token completed a 2FA challenge within auth_system.two_factor.sudo_ttl_minutes (default 15), pass through.
2. User has ≥1 verified 2FA method? Issue (or reuse) a challenge and return 403 with a challenge_token. The client completes POST /auth/2fa/challenge, then retries the original request.
3. User has no 2FA enrolled? Fall back based on auth_system.two_factor.middleware_behavior:
   • block → 403, step_up: enroll_2fa (client must redirect to enrollment).
   • force_enroll → 403, step_up: enroll_2fa (same signal; intended for a "set up 2FA now" modal).

Route::middleware(['auth:sanctum', 'auth.2fa'])->group(function () {
    Route::delete('account', ...);
    Route::post('billing/cancel', ...);
});

• password_confirm (default) — the user must have a fresh sudo window from POST /auth/password/confirm (valid for sudo_ttl_minutes). Works for users with or without 2FA.