Sanctum handles the majority of Laravel auth needs cleanly: SPA tokens, mobile tokens, simple API tokens. JWT solves a narrower problem, verifying a token without hitting a shared database or session store, which matters once several independent services need to trust the same token. If you do not have that problem, JWT adds complexity for nothing. This guide covers when JWT is the right call and how to build it end to end.

JWT vs Sanctum vs Passport

A Sanctum token is a database row: every request looks it up, which also makes revocation an instant delete. A JWT is self-contained, its signature alone proves validity, so any service with the key can verify it offline. Passport is a full OAuth2 server, which you only need when third-party clients request access on behalf of your users.

Anatomy of a JWT

A JWT has three parts: a header (signing algorithm), a payload of claims (subject, expiration, issuer, audience, custom data), and a signature. The signature prevents tampering, but the payload is only base64-encoded, not encrypted. Never put secrets or sensitive data in claims, anyone holding the token can decode and read them.

Installing and configuring the package

The original tymon/jwt-auth has been quiet for a while. The maintained community fork php-open-source-saver/jwt-auth is a drop-in replacement that tracks current Laravel and PHP. Install it, publish the config, generate the signing secret, point the api guard at the jwt driver, and have the User model implement JWTSubject.

// config/auth.php
'guards' => [
    'api' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
],

// app/Models/User.php
class User extends Authenticatable implements JWTSubject
{
    public function getJWTIdentifier(): mixed
    {
        return $this->getKey();
    }

    public function getJWTCustomClaims(): array
    {
        return ['role' => $this->role];
    }
}

Login, me, logout

class AuthController extends Controller
{
    public function login(LoginRequest $request)
    {
        if (! $token = auth('api')->attempt($request->validated())) {
            return response()->json(['message' => 'Invalid credentials'], 401);
        }

        return $this->tokenResponse($token);
    }

    public function me()
    {
        return new UserResource(auth('api')->user());
    }

    public function logout()
    {
        auth('api')->logout(); // invalidates the current token
        return response()->noContent();
    }

    private function tokenResponse(string $token)
    {
        return response()->json([
            'access_token' => $token,
            'token_type' => 'bearer',
            'expires_in' => auth('api')->factory()->getTTL() * 60,
        ]);
    }
}

Protecting routes and reading the user

Group protected routes under the auth:api middleware. Inside a controller, the api guard resolves the authenticated model from the token, with no database lookup unless you ask for one.

// routes/api.php
Route::post('auth/login', [AuthController::class, 'login']);

Route::middleware('auth:api')->group(function () {
    Route::get('auth/me', [AuthController::class, 'me']);
    Route::post('auth/refresh', [AuthController::class, 'refresh']);
    Route::post('auth/logout', [AuthController::class, 'logout']);
    Route::apiResource('orders', OrderController::class);
});

Refresh tokens done right

Keep the access token short-lived (15 to 60 minutes) and pair it with a longer-lived refresh token. Rotate the refresh token on every use, issuing a new one and invalidating the old, so a stolen refresh token works once before the legitimate user's next refresh reveals the theft.

public function refresh()
{
    $newToken = auth('api')->refresh(); // old token is blacklisted, new one issued

    return $this->tokenResponse($newToken);
}

Revocation with a Redis blocklist

A JWT cannot be un-issued, so forced logout and "log out everywhere" need a blocklist. Store the token ID (the jti claim) in Redis with a TTL equal to the token's remaining lifetime, so the entry disappears on its own once the token would have expired anyway. Check the blocklist in a middleware after auth:api.

class RejectBlockedTokens
{
    public function handle(Request $request, Closure $next)
    {
        $jti = auth('api')->payload()->get('jti');

        if (Redis::exists("jwt:blocked:{$jti}")) {
            return response()->json(['message' => 'Token revoked'], 401);
        }

        return $next($request);
    }
}

Security pitfalls to avoid

• ✓Algorithm confusion: pin the expected algorithm server-side, never trust the alg header from the token itself.
• ✓Do not store the token in localStorage for browser apps, use an httpOnly, Secure, SameSite cookie so an XSS bug cannot steal it.
• ✓Validate exp, iss and aud, not just the signature, so a token minted for another service is rejected.
• ✓Keep the payload small, it travels on every request and it is readable by anyone.
• ✓Serve the API over HTTPS only, and rotate the signing key on a schedule with an overlap window.

Testing JWT auth

public function test_protected_route_requires_a_valid_token(): void
{
    $user = User::factory()->create();
    $token = auth('api')->login($user);

    $this->getJson('/api/auth/me')->assertUnauthorized();

    $this->withToken($token)
        ->getJson('/api/auth/me')
        ->assertOk()
        ->assertJsonPath('data.id', $user->id);
}

JWT solves one specific problem: stateless verification across independent services. Implemented with short access tokens, rotating refresh tokens, a Redis blocklist and httpOnly cookies, it is solid. If that is not your architecture, Sanctum's simplicity and instant revocation win every time.