LexikJWTAuthenticationBundle: the Symfony JWT bundle documented by index
JWT authentication for your Symfony API
At a glance
- What is it?
- A PHP bundle for JWT authentication on Symfony APIs, whose README is essentially a table of contents to a reStructuredText documentation set shipped inside the repository.
- Who is it for?
- This bundle's most distinctive choice is that it does not treat documentation as a website to be maintained separately. The README is a table of contents, and the documents it points at live in the repository as reStructuredText, next to the code they describe and versioned with it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 102 days ago.
- What is it written in?
- Mainly PHP, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 8, 2026, and from our analysis. They are not legal advice.
Editorial analysis
A README that is really a table of contents
The README for LexikJWTAuthenticationBundle is short, and almost all of it is links. The opening line says what the thing is: a bundle that provides JWT authentication for a Symfony API. Then it points at the `Resources/doc` directory and says, in as many words, that the bulk of the documentation lives there.
The structure is worth looking at, because it shows what the maintainers consider the real path through the library. The first group is Getting started, with anchors for prerequisites, installation, configuration, usage and notes. The second group is Further documentation, listing a configuration reference, data customization and validation, functional testing, working with CORS requests, JWT encoder service customization, extending the authenticator, creating JWT tokens programmatically, a database-less user provider, accessing the authenticated JWT token, and invalidating a token on logout.
Two things stand out about that list. It covers CORS and a database-less user provider, which are the two questions that come up first when wiring a token API into an existing system, and it ends with token invalidation, which is the feature that changes the security model from purely stateless. The list also skips a number: the anchors run to 9-access-authenticated-jwt-token and then jump to 11-invalidate-token, with no 10 entry listed.
That gap is not necessarily an error. A release note for version 3.1.1 mentions an update to a document named 10-web-token.rst, so a tenth document exists and the README index simply does not list it. Worth knowing if you go looking for the web-token integration and conclude it does not exist.
What the source tree reveals about the design
With the documentation delegated to reStructuredText, the source tree becomes the place to look for the shape of the library. The bundle registers itself through `LexikJWTAuthenticationBundle.php` and `.symfony.bundle.yaml`, and configures itself from the `DependencyInjection/` directory.
The interesting directories divide the problem into stages. `Security/` holds the firewall integration, `Signature/` the token signing, `Encoder/` the token encoder service, and `TokenExtractor/` the part that pulls a credential out of an incoming request, which is the piece that matters if you are putting the token in something other than a standard header. `Event/`, `EventListener/`, `Subscriber/` and the `Events.php` file together are a substantial share of the tree, which tells you this bundle is as much about letting you hook into authentication events as about performing them.
The rest is standard Symfony bundle furniture with a couple of additions. There is `Command/` for CLI tasks such as generating key pairs, `Response/` for the responses the bundle returns on success and failure, `Helper/` and `Exception/` for shared utilities and error types, `Services/` for wiring, and an `OpenApi/` directory that is not mentioned in the README at all but tells you the bundle will describe its own endpoints if your API documentation setup reads them.
For tooling, the repository carries `ecs.php` for coding standards, `phpstan.neon` for static analysis, `rector.php` for automated refactoring, and `phpunit.xml.dist` for tests. A bundle with all four committed is one where the maintainers expect contributions.
The support matrix, and where the metadata stops
The compatibility statement is specific and current: the bundle is compatible with and tested against PHP above 8.2 and Symfony above 6.4 up to 8. That range spans three Symfony majors, which is worth noting because most bundles in this ecosystem narrow as they add support for a new major version rather than keeping the old ones alive.
GitHub reports 2,609 stars and 615 forks for lexik/LexikJWTAuthenticationBundle, with 120 open issues. The default branch is `3.x`, the last recorded push was 2026-07-01, and the license is MIT. The GitHub topics are authentication, jwt, php, symfony and symfony-bundle, and the repository description is JWT authentication for your Symfony API.
The distribution channel is Packagist rather than GitHub releases, and the README's first badge points at the stable version there. That distinction matters for security patches: this is a Composer dependency, so you pick up new versions by running an update in your project, not by watching a release page.
One small gap in the metadata is worth noting if you are evaluating whether the project is actively run. The repository has no homepage set in its GitHub metadata, which is unusual for a bundle with this adoption. The documentation lives on a separate site that the README index links into, and the README does not name a canonical site beyond the documentation itself. Nothing is wrong, but there is no single URL GitHub would show you in the sidebar.
Version 3.2.0 and the move to Symfony 8
Version 3.2.0, released 2026-07-01 in substance and tagged in December 2025 according to the release metadata, is the release that matters most for anyone starting now, because it is what added Symfony 8 support.
The headline item is a single pull request: support for Symfony 8.x together with the web-token suite 4.x. That pairing is the important detail. The bundle sits on top of the web-token libraries, so supporting a new Symfony major means supporting a new major of that dependency too, and the two land as one change rather than separately.
The rest of 3.2.0 is smaller and mostly about housekeeping. The `lcobucci/clock` dependency was removed, which is the sort of change that reduces your transitive dependency count. JWTUser phpdoc was improved. Extra data can now be passed when handling a successful authentication, which is how you attach something like a user identifier or a role set to the token payload. There is a typo fix in the 3.0 upgrade guide, and the GitHub Actions checkout step was bumped from version 4 to 5. A test run was added for PHP 8.5, so the project's forward compatibility checking is being done ahead of release rather than after.
The commit list also shows the shape of a volunteer-maintained project: one line of work is by a first-time contributor, several are by the same person who appears across versions, and one comes from a dependabot bump.
Version 3.1.1 was a month of authentication fixes
The release before that, version 3.1.1 from 2026-01-06, is a better illustration of what this bundle does than the feature releases are, because almost everything in it is a fix to authentication behaviour.
The most serious-sounding item is a fix for a wrongly silenced signing failure. When a signature does not verify, the bundle was swallowing the failure rather than propagating it. Depending on where that happened in the flow, a token that should have been rejected could have been treated as valid, which is exactly the class of bug you want caught early in a release rather than after a deployment. The author of that fix contributed it as a first contribution.
The other four items are smaller and no less instructive. Default values in the web-token services were wrong when encryption was disabled, so a configuration choice leaked into the behaviour of the token suite. The JWT cookie provider was not setting cookie flags correctly when values were provided, which is a secure and SameSite problem rather than a functional one. An implicit nullable parameter had to be fixed for PHP 8.4 compatibility. And the release added a test run with API Platform 4, meaning the bundle is checked against a real API framework rather than only its own test fixtures.
Between 3.1.0 and 3.2.0 there is also a deprecation fix for the Symfony Extension class. Small releases like this are the normal rhythm of a bundle that other people's login endpoints run on.
Upgrade guides kept in the repository
The tree contains four separate upgrade documents: `UPGRADE-2.0.md`, `UPGRADE-2.5.md`, `UPGRADE-2.12.md` and `UPGRADE-3.0.md`. For a library at version 3.2, keeping the notes for every minor version break is a deliberate choice, and a useful one, because token authentication configuration rarely changes in a way that is hard to reverse.
The README itself points only at the 1.x upgrade document and tells readers to see `UPGRADE-2.0.md`, which is a small inconsistency now that there are four files. Anyone upgrading from an older line will need to walk the chain rather than read a single page, and there is also a `CHANGELOG.md` at the root for the full history.
There is also no refresh token functionality in this bundle, and the README does not claim otherwise. The documentation set covers manual token creation and encoder customization, but the token lifecycle stays yours to manage. If you need refresh tokens you will pair it with a separate package, and the project's own ecosystem links point that way, with Gesdinet's refresh token bundle named alongside API Platform's documentation bundle and the lcobucci JWT library as things commonly used with it.
Community support is directed to Stack Overflow under the `lexikjwtauthbundle` tag, which the README calls the official support platform for the bundle, while GitHub issues are reserved for bug reports and feature requests. The project also asks for sponsorship to cover maintenance and development, and thanks Blackfire and JetBrains for free open source licences.
Editorial conclusion
This bundle's most distinctive choice is that it does not treat documentation as a website to be maintained separately. The README is a table of contents, and the documents it points at live in the repository as reStructuredText, next to the code they describe and versioned with it. That is why the compatibility statement, the configuration reference and the upgrade notes are all equally easy to check. For adoption, the facts that matter are narrow: PHP above 8.2, Symfony above 6.4 through 8, MIT licensing, and a 3.x default branch whose 3.2.0 release added Symfony 8 and web-token 4.x support. The thing to plan around is that stateless tokens do not expire on logout by default, and the bundle ships a separate document on invalidating a token when you need that behaviour. Read the configuration reference and the invalidation document before wiring up your login route, not after.
Frequently asked questions
What is JWT authentication and how does it work?
A JWT is a compact token that carries claims as a signed payload, so a server can verify who sent a request without looking up a session or calling a third party on every call. In this bundle the flow is: credentials arrive, the Security layer authenticates them, the Encoder service turns the result into a token using the keys under Signature, and TokenExtractor pulls the token back out of each incoming request. The README's Getting started section points at prerequisites, installation, configuration and usage as the order to follow, and the configuration reference in Resources/doc has the option by option detail.
How can I decrypt a bearer token?
You generally cannot, because a JWT is signed rather than encrypted. The payload is base64 encoded so any client can read its claims, and the signature is what proves the token was not altered. What the bundle does is sign tokens and verify that signature on the way back in. If you need to read a token you issued, decode the claims; if you need to change how tokens are produced, the documentation set includes a document on JWT encoder service customization, and the Encoder and Signature directories in the repository are where that behaviour lives.
Can I invalidate a JWT token after I log out?
Yes, and the repository ships a document for it. The README's Further documentation list ends with Invalidate token on logout, pointing at Resources/doc/11-invalidate-token.rst, so logout invalidation is a supported feature rather than something you have to build. Note that this is opt-in: the default behaviour of a stateless token is that it stays valid until it expires, which is why the bundle treats this as a separate topic rather than part of the basic setup.
Is JWT authentication secure?
The security model depends on configuration and on which token library does the work. This bundle supports PHP above 8.2 and Symfony above 6.4 up to 8, MIT licensed, and its default branch is 3.x, with 3.2.0 adding Symfony 8 and web-token 4.x support. The release history shows attention on the details that matter: 3.1.1 fixed a wrongly silenced signing failure, fixed default values in the web-token services when encryption was disabled, and fixed missing cookie flags. The bundle does not do refresh tokens, so the token lifecycle stays under your control.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/lexik-lexikjwtauthenticationbundle)