Spring Boot JWT: A Short-Lived Access Token and Revocable Refresh Token Template

What This Template Solves and Who It Is For

The repository addresses a specific tension in JWT-based authentication: access tokens that are stateless and fast to verify cannot be revoked, while revocable sessions require server-side state. The README states the project takes a position on this trade-off. It uses short-lived access tokens that are fully stateless and cannot be revoked, paired with refresh tokens that are stateful and revocable. This design targets developers building a Spring Boot API who want a reference implementation for token-based auth without session cookies. It is aimed at engineers who need a working example to copy and adapt, not at teams looking for a turnkey authentication server. The target user is comfortable with Spring Security and MySQL and wants to see how these pieces fit together in a single service.

The Hybrid Token Mechanism: Stateless Access, Stateful Refresh

The core mechanism is a hybrid approach. Ordinary API requests carry an access token that is verified using only the signature, so no database lookup happens on those requests. The README notes this preserves statelessness where it matters for throughput. The refresh token, however, is stored server-side and can be revoked. When the access token expires, the client sends the refresh token to a refresh endpoint. The server checks that refresh token against its storage, issues a new access token, and rotates the refresh token, meaning the old one is invalidated and a new one is issued. The README says the refresh token is stateful and revocable, which allows it to be invalidated if a user logs out or if the token is compromised. This design gives up statelessness only on the refresh call, which is comparatively rare. The project does not detail the exact storage schema in the README, but the description mentions MySQL, so the refresh token state presumably lives in a database table.

Getting It Running: Commands and Configuration

The README does not provide explicit setup commands, but the repository is a standard Maven-based Spring Boot project. To run it, you would clone the repository, configure a MySQL database, and adjust application properties such as the datasource URL, username, and password. The project uses Spring Boot and Spring Security, so you would run `mvn spring-boot:run` or package it with `mvn package` and then run the resulting JAR. The README mentions the CI workflow file, so you can inspect `.github/workflows/ci.yml` to see the build and test commands used. Configuration keys for JWT secrets and expiration times are not listed in the README, so you must open the `application.yml` or `application.properties` file in the repository to find them. The README does not document the exact endpoints, but a typical flow would be a `/login` or `/auth` endpoint that returns both tokens, and a `/refresh` endpoint that takes the refresh token. You should look at the controller classes in the source to confirm the actual paths.

A Genuine Limitation: The Access Token Cannot Be Revoked

The most significant limitation is inherent to the design. The access token is stateless, so it cannot be revoked before it expires. If a user is banned or their privileges are removed, the access token remains valid until its short lifetime ends. The README acknowledges this trade-off explicitly, stating that 'true statelessness and revocation are mutually exclusive.' This means the project is the wrong tool if your application requires immediate revocation of a user's access, such as in a high-security environment or when dealing with compromised accounts. The short-lived access token mitigates the risk, but the window of vulnerability remains. Additionally, the README notes that access tokens can contain outdated authorization claims. If a user's role changes, the token still carries the old claims until it expires. For applications that need fine-grained, real-time authorization, this template is not suitable without additional checks.

A Real Alternative: Session-Based Authentication with Cookies

A direct alternative is traditional session-based authentication, where the server stores session data and issues a cookie. The README itself lists the benefits of token-based auth over sessions, including no need for CSRF protection, better mobile integration, and no distributed session store. But the session approach has a different trade-off: it allows immediate revocation by deleting the session, at the cost of server-side state on every request. Spring Security supports session management natively, and you would not need JWT at all. The key difference is that sessions are stateful for every request, so they require a session store, which can be a database or an in-memory cache like Redis. This means every authenticated request hits that store, which is slower under high load. The JWT approach in this project avoids that per-request lookup for access tokens, but gives up immediate revocation. If your priority is control over user sessions, sessions are the better choice; if your priority is throughput on API requests, this JWT template is closer to what you want.

Maintenance, Upgrade Cost, and License Implications

The repository is archived as not archived, but the last push date is unknown, and there are no recent releases retrieved. This suggests the project may not be actively maintained. The README references a CI workflow, but without recent commits, you cannot assume it is up to date with the latest Spring Boot or Spring Security versions. The maintenance cost is on you: you must update dependencies yourself, and you must verify that the security configuration still matches current Spring Security APIs, which have changed significantly across versions. The license is MIT, which permits commercial use, modification, and distribution, with attribution required. That is permissive, but it comes with no warranty, so you are responsible for security hardening. There are no release notes to guide upgrades, so you must rely on the code itself. Before adopting, check the `pom.xml` for the Spring Boot version and compare it to the latest stable release.

The Bottom Line: A Teaching Tool, Not a Production Dependency

This project is best viewed as a teaching aid. It shows a clear, readable implementation of a common JWT authentication flow, and the README explains the underlying concepts well. The hybrid token design is a practical compromise between statelessness and revocability. However, it is not a maintained library or a production-ready service. There are no releases, no versioned artifacts, and no explicit configuration documentation. You will need to read the source code to understand the exact endpoints, token expiration settings, and database schema. The README's own list of trade-offs, including XSS vulnerability and outdated claims, should be taken seriously. For a production system, you would likely start from this template and then add features like token blacklisting, more robust refresh token storage, and protection against token replay. The value is in the starting point, not the finish line.

Editorial conclusion

Adopt this project if you are a Java developer who wants a minimal, readable JWT authentication service to adapt for a Spring Boot application, especially one that needs short-lived access tokens and revocable refresh tokens. Do not use it as a drop-in production dependency; it is a template, not a library. Before use, verify the Spring Boot and Spring Security versions against your target environment, confirm the MySQL schema and refresh token rotation logic meet your security requirements, and check the MIT license terms for your use case. The core judgement: this is a solid educational base, but you must harden and update it yourself.

Official sources

1. Official README
2. Project repository