10 min TL;DR — Strapi introduced a new Access + Refresh Token session model in v5.24.x. Headlockr 4.2.3 is now fully compatible with this system.
Upgrade path: no breaking changes in Headlockr — just upgrade Strapi and Headlockr to the latest versions and you’re good to go.
Watch the demo
https://www.youtube.com/watch?v=_RUdNUuf_wE
⚠️ Disclaimer: The demo below was performed in a controlled environment and is intended purely for educational and awareness purposes. No live systems were harmed or accessed.
Why Strapi’s new auth matters for real-world security
Older authentication flows often relied on long-lived JWTs. That creates unnecessary exposure when tokens leak, whether through a spoofed public Wi-Fi, a typosquatted domain, or a social-engineering email. Strapi’s new model replaces that pattern with short-lived access tokens that expire quickly, paired with refresh/session tokens that are tracked and revocable on the server. In practice, that means proper logout, token rotation, and per-session control—a major improvement for anyone serious about Strapi security.
From a product perspective, this also reduces operational risk. When an admin logs out, their session actually ends. When an access token expires, a new one is issued through a secure rotation endpoint. And because sessions are stored server-side, you gain the ability to invalidate, audit, or limit them per user, device, and session.
What’s new in Headlockr 4.2.3
We’ve aligned Headlockr with Strapi’s modern authentication architecture so you can take advantage of the stronger security model without friction. Headlockr 4.2.3 adds full support for the Access + Refresh Token flow used by the Admin Panel and the optional refresh mode in the Users & Permissions plugin. Under the hood we also refactored critical paths to make the plugin faster and more predictable, and we fixed several bugs to smooth your daily workflows. The result is a drop-in upgrade: install the latest versions, verify your login/logout and token rotation, and keep building. There are no breaking changes in Headlockr for this release.
Headlockr ≥ 4.2.3 — supports Strapi’s newest authentication/session model.
Strapi v5.24.x — introduces the new session architecture used by Headlockr.
Strapi v4 — out of scope for this change (unrelated to the new session model).
How the new model works
With Strapi v5.24.x and Headlockr 4.2.3:
- The Admin Panel authenticates using short-lived access tokens that are validated against active sessions. Refresh tokens are stored in an httpOnly cookie so they aren’t accessible to client-side scripts.
- The Users & Permissions plugin can remain on the legacy long-lived JWT flow, but we recommend opting in to the refresh mode for session-backed access and refresh tokens. This mode unlocks real logout and token rotation, which is essential for modern security baselines.
Because sessions are tracked server-side, you can revoke sessions, enforce device limits, and tune TTLs without redeploying your application.
View the full PR here: https://github.com/strapi/strapi/pull/24346
Quick configuration examples
Below are minimal examples to help you get started. You don’t need to copy them verbatim—treat them as references you can adapt to your environment and secrets management.
```js
// config/plugins.js
module.exports = {
'users-permissions': {
config: {
jwtManagement: 'refresh', // or env('UP_JWT_MANAGEMENT', 'refresh')
sessions: {
accessTokenLifespan: env.int('UP_SESSIONS_ACCESS_TTL', 7 * 24 * 60 * 60),
maxRefreshTokenLifespan: env.int('UP_SESSIONS_MAX_REFRESH_TTL', 30 * 24 * 60 * 60),
idleRefreshTokenLifespan: env.int('UP_SESSIONS_IDLE_REFRESH_TTL', 7 * 24 * 60 * 60),
httpOnly: env.bool('UP_SESSIONS_HTTPONLY', false),
cookie: {
name: env('UP_SESSIONS_COOKIE_NAME', 'strapi_up_refresh'),
sameSite: env('UP_SESSIONS_COOKIE_SAMESITE', 'lax'),
path: env('UP_SESSIONS_COOKIE_PATH', '/'),
domain: env('UP_SESSIONS_COOKIE_DOMAIN'),
secure: env.bool('UP_SESSIONS_COOKIE_SECURE', process.env.NODE_ENV === 'production'),
},
},
},
},
};// config/admin.js
module.exports = {
auth: {
secret: env('ADMIN_JWT_SECRET'),
sessions: {
accessTokenLifespan: 1800,
maxRefreshTokenLifespan: 30 * 24 * 60 * 60,
idleRefreshTokenLifespan: 7 * 24 * 60 * 60,
maxSessionLifespan: 7 * 24 * 60 * 60,
idleSessionLifespan: 3600,
},
cookie: {
sameSite: 'lax',
path: '/admin',
domain: env('ADMIN_COOKIE_DOMAIN'),
},
},
};
In production, prefer httpOnly cookies for refresh tokens and route all admin/API traffic over HTTPS. Test rotation (/admin/access-token and /api/auth/refresh) and logout flows in staging before rolling out widely.
Upgrade in minutes
Upgrading is straightforward. Bring Strapi to v5.24.x or later, then update Headlockr to v4.2.3 or later:
# Strapi
npm install strapi@latest @strapi/*@latest
# Headlockr
npm install headlockr@latest
# or: yarn add headlockr@latest / pnpm add headlockr@latest
After installation, log into the Admin Panel, confirm your access token expires as expected, and verify that a refresh flow renews access cleanly. If your project uses the content API for end-users, consider enabling the refresh mode in Users & Permissions to gain the same session-backed benefits.
Why Choose Headlockr Right Now?
Security isn’t a one-time checkbox. Strapi’s new authentication and session model significantly raises the baseline, and Headlockr is designed to meet it head-on. If you care about protecting your Strapi Admin Panel and Users & Permissions flows without adding complexity, upgrading today is the most effective move you can make.
If you’re strengthening authentication, don’t stop at short-lived tokens. Multi-Factor Authentication (MFA) is the next critical layer for blocking account takeover. We explain why "passwords alone aren’t enough", how leaked credentials fuel attacks, and why leaders like Microsoft report that MFA can stop 99.9% of account-compromise attempts.
Read the full post: Why your Strapi admin needs MFA, not just passwords
Proven and Trusted by Industry Leaders
Leading digital agencies and businesses already trust Headlockr, demonstrating its effectiveness and reliability. If you landed here searching for “Strapi authentication”, “Strapi access token refresh”, “Strapi session management”, “Strapi security best practices”, or “Headlockr Strapi plugin”, this update is for you. The shift to short-lived access tokens and session-backed refresh tokens is the future-proof route for Strapi security. By adopting Strapi v5.24.x and Headlockr 4.2.3, you get real logout, token rotation, and server-side revocation—the cornerstones of modern authentication.
Your Wake-Up Call: Act Immediately
Strapi’s new authentication and session model raises the baseline for Strapi security. Headlockr 5.2.3 meets that baseline head-on with full compatibility, performance improvements, and a smooth upgrade path. If you care about protecting your Strapi Admin Panel and Users & Permissions flows without adding complexity, upgrading today is the most effective move you can make.
Protect your Strapi environment immediately and secure your future with Headlockr.
