- How do I install d076/sanctum-refresh-tokens in a Laravel app?
- Install it with Composer using composer require d076/sanctum-refresh-tokens, then run the package migrations. It is designed for Laravel 12 or 13 on PHP 8.3+ with Sanctum already configured. After installation, wire the package's auth flow into your login and refresh endpoints and test token issuance and rotation.
- Does d076/sanctum-refresh-tokens support Laravel 12 and Laravel 13?
- Yes. The v4 release declares compatibility with laravel/framework ^12.0|^13.0 and is intended for Sanctum-based applications on those versions. Laravel 11 support was dropped as a breaking change, so applications still on Laravel 11 must upgrade before adopting v4. Validate against the exact Laravel minor version and Sanctum version used in production.
- What PHP version is required by sanctum-refresh-tokens?
- The package requires PHP 8.3 or newer. PHP 8.2 support was dropped in the v4 release, so teams running PHP 8.2 need to upgrade their runtime first. The package is evaluated for PHP 8.3 through 8.5.
- How does refresh token rotation work in this Laravel Sanctum package?
- The package issues short-lived access tokens alongside revocable refresh tokens. When a refresh token is used, it is rotated so the old refresh token should no longer be reusable, reducing the impact of token theft. You should persist the new token pair and handle replay attempts as authentication failures. Exercise the refresh path in staging before deploying.
- How do I handle existing personal_refresh_tokens rows after the abilities migration?
- The abilities migration is the primary integration step, and existing refresh-token rows need an explicit backfill or reissue strategy. Confirm how the abilities column is defaulted or backfilled in your environment before rollout. If existing refresh tokens cannot be mapped to the correct abilities, invalidate them and force reauthentication rather than risk over- or under-permissioned tokens.
- Does sanctum-refresh-tokens preserve token abilities and scopes on refresh?
- Yes, v4 persists token abilities on personal_refresh_tokens and preserves them through the refresh flow. This fixes a material scoping defect where the refresh flow could reset scoped access-token abilities to ['*'], potentially widening permissions. Teams using scoped API tokens should prioritize this upgrade and still test scoped-token refresh paths.
- What breaking changes are in d076/sanctum-refresh-tokens v4.0.0?
- v4 drops Laravel 11 and PHP 8.2 support, requiring Laravel ^12.0|^13.0 and PHP 8.3+. It adds an abilities migration for personal_refresh_tokens and changes refresh behavior so scoped abilities are preserved instead of reset to ['*']. Treat this as a framework-level upgrade gate and define a token backfill or reissue plan before deploying.
- How should I test refresh token login, logout, and replay protection before production?
- In staging, exercise login, refresh, logout, password reset, replay protection, and scoped-token refresh paths against the same database engine you use in production. Run the abilities migration and backfill plan with representative token data, then verify TTL enforcement and refresh failure monitoring. Cross-database CI covers SQLite, PostgreSQL, and MySQL, but you should still validate your production database version.
- Is d076/sanctum-refresh-tokens production-ready and actively maintained?
- The package is MIT licensed and shows positive maintenance signals, including a rewritten README, Pest/Testbench coverage, a cross-database CI matrix, and PHPStan/Larastan level 6 analysis. Support is community/open-source only, with no commercial SLA, so your team should own dependency tracking and security review. Keep an internal runbook for token migration, rollback, and reauthentication decisions.
- What are the alternatives to adding refresh tokens to Laravel Sanctum?
- Alternatives include using Sanctum's default long-lived API tokens, implementing a custom short-lived access-token plus refresh-token flow, or using a full OAuth2 server package such as Laravel Passport. Sanctum is simpler for first-party SPA and mobile authentication, while Passport may fit third-party OAuth2 use cases. Evaluate token lifetime, revocation, rotation, and scoped abilities against your security requirements.