Laravel Sanctum custom guard

Laravel Sanctum custom guard

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Debugging auth:sanctum Guard Mismatches in Multi-Guard Applications

You have configured your Laravel application with distinct authentication guards for standard users and administrators, defined within config/auth.php. Your setup correctly maps the user and admin guards to specific Eloquent models (User::class and Admin::class) using the token driver. When you attempt to access a protected route via an API token—such as Route::get('admins/auth/user', 'AuthController@user')->middleware('auth:sanctum')—you encounter an InvalidArgumentException. The error explicitly states that the auth guard [web] is not defined.

This specific exception indicates a fundamental mismatch between how Laravel Sanctum interprets your request and the guards you have actually registered in your application. Despite adding a 'guard' => 'admin' configuration to config/sanctum.php, the issue persists. Understanding why this happens requires digging into how Sanctum initializes its guard context versus how the standard authentication package defines defaults.

The Default Guard Trap

In Laravel, the auth:sanctum middleware is designed primarily for stateless token authentication. However, when you invoke methods like $request->user() or $this->user() within your controller, the underlying implementation often attempts to resolve a guard named web. This behavior is inherited from the broader Auth facade logic which assumes a default web guard exists for session-based requests.

Sanctum does not automatically register a web guard in your guards array unless you explicitly define it or configure Sanctum to use one of your existing guards as the fallback. When you see the error InvalidArgumentException: Auth guard [web] is not defined, it means the middleware successfully authenticated the token against your admin or user guard, but the subsequent logic attempting to retrieve the user instance failed because it looked for a non-existent web guard.

Resolving the Guard Conflict

The most robust solution is to ensure that your Sanctum configuration aligns with your actual application guards without relying on implicit defaults. Simply adding 'guard' => 'admin' to config/sanctum.php under the middleware section often does not resolve the root cause because that block primarily handles CSRF and cookie encryption, not the primary authentication guard resolution for API tokens.

To fix this, you should explicitly define a default guard in your Sanctum configuration that points to one of your existing guards. Update config/sanctum.php as follows:

return [
    // ... other settings
    'middleware' => [
        'verify_csrf_token' => App\Http\Middleware\VerifyCsrfToken::class,
        'encrypt_cookies' => App\Http\Middleware\EncryptCookies::class,
    ],
    
    // Explicitly set the default guard to one of your existing guards
    // This prevents Sanctum from trying to resolve a non-existent 'web' guard
    'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', '')),
    
    // Ensure this line is present and points to a valid guard name defined in auth.php
    'guard' => 'admin', 
];

However, ensure that the value 'admin' here matches the key in your config/auth.php exactly. In your provided example, you have both user and admin guards defined with the token driver. Since your route is prefixed with admins, targeting the admin guard makes logical sense.

Verifying the Fix

After updating the configuration, clear your application cache to ensure Laravel picks up the new settings:

php artisan config:clear
php artisan cache:clear

Once cleared, retry the request that triggered the exception. The auth:sanctum middleware should now resolve the user correctly against the admin guard without throwing an InvalidArgumentException regarding a missing web guard.

If you find yourself needing to switch between guards dynamically or require different behavior for specific routes, consider creating separate middleware instances per route. For example, if you have a mix of API endpoints requiring different users, defining custom middleware that passes a specific guard name to the resolver can provide more granular control than relying on global defaults.

For further guidance on managing complex authentication setups in Laravel, resources like https://laravelcompany.com offer deep dives into securing your APIs and handling multiple user types efficiently.

Our network