jwt-auth: putting a bearer token where Laravel's session guard used to be

A README that is essentially a documentation pointer

It is worth being blunt about what this repository's README contains, because it shapes how you evaluate the project. There is a banner image, six badges, one section heading with a link, a security note, and a license line. There is no feature list, no installation command, no configuration example, and no code sample.

The badges themselves carry real information. Four of them point at Packagist, which tells you the Composer package name is `tymon/jwt-auth` rather than `tymondesigns/jwt-auth`, and that a separate dev version is tracked from a `develop` branch. The PHPUnit and Codecov badges point at a `develop` branch too, while the default branch is `2.x`. That layout tells you the project runs a stable line and a development line in parallel, which is what you want from something carrying an auth guard.

The one substantive paragraph in the README is about security reporting. It asks that security issues be emailed to the maintainer's address rather than opened on the issue tracker, which is the correct convention and a small signal about how the project is run.

So the README is not a place to evaluate the design. It is a signpost, and the destination is a documentation site at jwt-auth.com.

What the package is for inside a Laravel application

The GitHub description states the scope in six words: JSON Web Token Authentication for Laravel and Lumen. The topics list narrows it to authentication, jwt, laravel and php. So this is not a JWT library, and it is not an OAuth server. It is the adapter that lets a Laravel application authenticate a caller from a bearer token instead of from a session cookie, which is what a mobile client, a single page application, or a service-to-service caller needs.

That framing matters more than it first appears, because Laravel's stock authentication is a guard over a session. The framework gives you that for free, and it is the right answer for a server-rendered application. The moment your client is not a browser tab on your own domain, cookies stop being convenient and a signed token becomes the practical choice. This package is the piece that makes that swap without rewriting your application's auth logic from scratch.

The repository structure is consistent with that role rather than with a crypto library. There is `src/` for the implementation, `config/` for the package configuration that a Laravel user publishes and edits, `tests/` for the suite that the PHPUnit badge reports on, and `docs/` alongside an `mkdocs.yml`, which is how the documentation site is built. There is no `openssl/` or `crypto/` directory, because the signing and verification work is not done here.

The dependency that does the actual signing

Version 2.3.0, published 2026-03-06, contains one line that tells you more about the architecture than any amount of description would: it allows `lcobucci/jwt` v5.

That is a third-party library for creating and validating JSON Web Tokens in PHP, and this package depends on it rather than implementing JWT signing itself. That is the right division of labor and it has a consequence for you. Token format, algorithm handling, and key management come from a library with its own release cycle, and jwt-auth's job is to wire it into Laravel's authentication stack: which guard issues the token, which middleware reads it, how the payload maps to your user model, and what happens when a token is expired.

The v5 allowance is a breaking-adjacent event. Moving from v4 to v5 of a JWT library is the kind of upgrade that changes constructor signatures and encoding behaviour, so a package that allows it in a release has done adaptation work for you. Version 2.3.0 also added support for Laravel 13 and made a documentation change to inherit an existing doc rather than redeclaring it.

The pattern across the last three releases is a framework compatibility story. Version 2.2.0, from 2025-02-28, added PHP 8.4 and Carbon 3 support and allowed Laravel 12. Version 2.2.1, from 2025-04-16, was a single fix for a Carbon 3 change to `diffInMinutes`. Both of those are dependency-drift fixes, not feature work, which is what a well-behaved Laravel package looks like between majors.

Version support as a maintenance signal

There is one fact in this repository that deserves more attention than it usually gets, and it is the date of the last push: 2026-03-06.

That is the same day version 2.3.0 was tagged, and it is also the date of the most recent commit to the default branch, which is `2.x`. Read together with the release history, it says the project is at a settled point after a compatibility release rather than mid-cycle. Nothing about the release notes suggests anything is in flux.

The open issue count sits in the six hundreds, which is worth setting against the fact that a Laravel package accumulates issues from many framework versions at once. An issue filed against Laravel 8 does not tell you anything about the health of the version 2 line today, so the raw number is not a useful signal on its own. What would be useful is the rate of closing issues and the age of what remains open, and the release history only speaks to the former indirectly.

The honest position is that this is a mature package with a slow, careful release rhythm, and the way to read its current state is the issue tracker filtered to the `2.x` branch, not the headline count.

What lives on jwt-auth.com and why the split exists

Because the README defers everything, it is worth naming what you are being sent to and why a project would make that choice.

A package like this has to document several audiences at once: how to install and publish the config, how to register the guard, how to add the middleware to protected routes, how the token payload maps to fields on your user model, how refresh and blacklisting work, and what changes between major versions. That is a substantial manual, and it changes on a different cadence than the code.

Hosting it on a dedicated domain rather than in the repository means it can be versioned and pointed at. The default branch being `2.x` and the docs being separate is how a project documents more than one major line at a time, with each version of the site matching a version of the code. The MkDocs configuration in the repository tree is the build system behind that site.

The trade-off is real and worth naming. Nothing in the repository tells you how the guard is registered or what a request needs to carry, so you cannot evaluate the integration surface from the code alone. Anyone comparing this against Laravel Sanctum or a hand-rolled guard will have to read the external documentation for both before the comparison means anything. Package names, install commands, and configuration keys stay in their original form in that documentation.

Editorial conclusion

This package does one job for Laravel applications that cannot use a session cookie, and it has kept that job current against both the framework and the JWT library underneath it. The two facts worth carrying forward are that version 2.3.0 allowed lcobucci/jwt v5 and added Laravel 13 support, and that the project's default branch is `2.x` rather than a trunk, so you are choosing a maintained major line rather than following the newest code. Everything else you need to decide, from how the guard is registered to how token refresh works, lives on jwt-auth.com rather than in the repository, which is the single biggest difference between evaluating this and evaluating most Laravel packages. Last push was on 2026-03-06, and the security contact is an email address rather than the issue tracker.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tymondesigns/jwt-auth on GitHub