Auth guard [:api] is not defined?

Auth guard [:api] is not defined?

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

Stefan Bogdanescu

Founder & Senior Architect

Auth guard [:api] is not defined?

You are staring at a stack trace that says Auth guard [:api] is not defined. The error message itself seems contradictory. You have explicitly configured your config/auth.php file to use the 'passport' driver for the api guard, and you have registered the users provider. Your routes/api.php file even wraps your protected endpoints in a middleware group named auth::api. Logically, everything should work.

The problem lies in a subtle distinction between how Laravel registers guards versus how Passport handles authentication tokens. When you apply the auth:api guard to a route, Laravel expects that specific guard name to resolve to a valid session or token provider configuration within the global auth system. However, when using Laravel Passport, the authentication logic is often delegated entirely to the Passport service itself, bypassing the standard Auth::guard() check used by generic guards.

If you attempt to use auth:api middleware with Passport without careful setup, Laravel attempts to validate the token against the standard auth guard registry, failing because it doesn't find a matching entry in the way it expects for Passport's specific token handling flow. This is particularly common when mixing standard session-based guards (like web) with Passport's JWT-style authentication.

To resolve this, you must ensure that the api guard is correctly registered and that your application understands how to handle Passport tokens within that context. The most robust solution involves verifying that your config/auth.php file explicitly maps the api guard to the passport driver with the correct provider. Here is a standard configuration snippet that often resolves the issue:

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

Once this configuration is in place, you must ensure that the auth:api middleware group is actually being recognized by Laravel's core. Sometimes, simply adding the guard to the config isn't enough if the Passport package hasn't been fully bootstrapped or if the token configuration is missing from your .env file. You need to verify that APP_KEY is set and that PASSPORT_CLIENT_ID and PASSPORT_CLIENT_SECRET are populated if you are using client credentials, though for standard user tokens, this might not be strictly necessary depending on your setup.

However, there is a more fundamental architectural pitfall here. In many Passport implementations, the logout process is handled differently than a standard session guard logout. Standard guards rely on destroying a session in the storage/framework/sessions directory (or Redis). Passport relies on invalidating tokens stored in its own database table or clearing specific scopes. If you are trying to use the generic auth:api guard middleware for a logout endpoint, you might be fighting against the underlying mechanism.

Instead of relying solely on the generic auth:api guard for the middleware group, consider defining a custom middleware that explicitly checks for a valid Passport token and then invalidates it. This approach gives you direct control over the token lifecycle without relying on the default guard resolution logic which might be throwing the "not defined" exception due to internal mapping issues.

Here is an example of how you might structure your routes if you decide to stick with the middleware group but ensure the guard is recognized:

Route::group(['prefix' => 'auth', 'middleware' => \Illuminate\Passport\Http\Middleware\Authenticate::class], function () {
    Route::post('login', 'AuthController@login');
    Route::post('signup', 'AuthController@signup');

    Route::group(['middleware' => 'auth:api'], function () {
        Route::get('logout', 'AuthController@logout');
        Route::get('user', 'AuthController@user');
    });
});

The key takeaway is that the error usually indicates a mismatch between the expected guard driver and the actual Passport implementation. By ensuring your config aligns with the Passport requirements and potentially wrapping the routes in the dedicated Authenticate middleware provided by the package, you can bypass the generic guard resolution issue entirely. This allows your logout controller to focus on what it does best: revoking the user's access tokens rather than managing session destruction logic.

For further guidance on configuring Passport with Laravel Sanctum or handling token lifecycle events in complex applications, check out https://laravelcompany.com.

Our network