README

JWT for Laravel

Native RS256 user tokens and HS256 service tokens for Laravel — guard drivers, a jti denylist and claim-based authorization, with zero third-party crypto (the JOSE core comes from our own crypto-for-laravel). Single-algorithm pinning, mandatory iss/aud pins and loud, fail-closed misconfiguration are built in.

Installation

Requires PHP 8.4 (ext-openssl, ext-json), and Laravel 12 or 13.

composer require roundly-consulting/jwt-for-laravel
php artisan jwt:generate-keys   # issuer apps: writes storage/jwt-private.key + storage/jwt-public.pem

Set JWT_ISSUER and JWT_AUDIENCE — both pins are required, and an unset one throws. The denylist lives in the redis cache store unless you set JWT_DENYLIST_STORE.

Usage

Declare a guard in config/auth.php — the package provides the jwt and service-jwt drivers:

'guards' => [
    'api' => ['driver' => 'jwt', 'provider' => 'users'],   // drop the provider to build a TokenUser from the claims alone
],

Mint a token, verify it anywhere with the public key, and revoke it:

use RoundlyConsulting\Jwt\Facades\Jwt;
use RoundlyConsulting\Jwt\UserTokens\AccessTokenRequest;

$issued = Jwt::mintAccessToken(
    AccessTokenRequest::for($user->id)
        ->email($user->email, verified: true)
        ->permissions('posts.view', 'posts.edit')
);

$claims = Jwt::verify($issued->token);   // RS256, iss and aud pinned
$claims->string('sub');                  // "42"

Jwt::logout($issued);                    // denylist the jti until it expires

Then protect routes as usual:

Route::middleware('auth:api')->get('/me', fn () => ['id' => auth()->id()]);

Documentation

The full documentation — configuration, every feature and its API, and testing — lives on our website: roundly-consulting.com/open-source/docs/jwt-for-laravel

Release notes are in CHANGELOG.md. To contribute, see the contributing guide.

Support our work

This package is free and open source, built and maintained by Roundly Consulting. If it saves you time, please consider supporting our open-source work — a one-time donation, a monthly pledge on Patreon or a crypto donation helps fund maintenance, new features and new packages.

License

The MIT License (MIT). See LICENSE.md. Maintained by roundly-consulting.

roundly-consulting / jwt-for-laravel

Package info

Security

Fund package maintenance!

Statistics