Download the PHP package d076/sanctum-refresh-tokens without Composer

Laravel Sanctum Refresh Tokens

Refresh tokens on top of Laravel Sanctum. Sanctum issues long-lived personal access tokens; this package adds a short-lived access token paired with a longer-lived, single-use refresh token, so a client can silently obtain a fresh pair without re-authenticating — the standard pattern for SPAs and mobile apps.

Features

• Access + refresh token pairs issued together, each with its own TTL.
• Single-use rotation — exchanging a refresh token deletes it and its bound access token, then issues a brand-new pair. Replaying a used token fails.
• Hashed at rest — refresh tokens are stored as SHA-256 hashes and compared in constant time (hash_equals); the plaintext is only ever returned to the client.
• TTL enforced on lookup — expired refresh tokens are never matched.
• Credential login, logout and password reset helpers that revoke the right tokens.
• Override-friendly — no routes or controllers are shipped; you wire your own. Services are bound behind interfaces, and the user model's email/password fields are configurable.
• Prune command for housekeeping expired tokens.

Requirements

Tested against PHP 8.3 / 8.4 / 8.5 and Laravel 12 / 13 on SQLite, PostgreSQL and MySQL.

Installation

Publish and run the migration (creates the personal_refresh_tokens table):

This package builds on Sanctum's personal_access_tokens table, so make sure Sanctum itself is installed and migrated (php artisan install:api on a fresh app).

Upgrading from 3.x

4.0 adds an abilities column to personal_refresh_tokens (so a token's scope is preserved across refreshes). Re-publish and migrate to pick it up:

Refresh tokens issued before the upgrade have no stored scope and fall back to ['*'] on their next refresh.

Setup

Extend your authenticatable model from AuthenticatableUser:

AuthenticatableUser already pulls in Sanctum's HasApiTokens plus this package's refresh-token behaviour. If you can't change your base class, use the trait directly and implement the contract instead:

Configuration

Token lifetimes are read from Sanctum's config (config/sanctum.php). Add the keys this package uses alongside Sanctum's own:

If a key is absent the built-in defaults above are used, so the package works out of the box. The optional sanctum.token_prefix is honoured for refresh tokens too (useful for secret-scanning).

Usage

The package ships no routes or controllers — you stay in control of your API surface. Inject the services where you need them.

Issuing tokens

createTokens() accepts optional overrides:

It returns a TokensDTO:

Logging in with credentials

remember selects between the two refresh-token TTLs (refresh_token_expiration vs refresh_token_expiration_no_remember).

Already have the user (e.g. social login)? Skip credentials:

Refreshing

The old refresh token and its bound access token are deleted before the new pair is issued, so a stolen-and-replayed token is rejected on the second use.

Logout

Behind the auth:sanctum guard, the authenticated request carries the current access token, so logout can revoke exactly that pair:

Password reset

Hashes the new password, saves it, and revokes all of the user's access and refresh tokens:

Revoking tokens directly

Pruning expired tokens

A console command removes refresh tokens that expired more than --hours ago (default 24):

Schedule it next to Sanctum's own pruning:

Customisation

Custom email / password columns

If your model doesn't use email / password, expose the column names and the package will pick them up:

Swapping the service implementations

Both services are bound behind interfaces, so you can rebind your own in a service provider:

How it works

• A refresh token is {id}|{token}, where {token} is 40 random characters plus a CRC32b checksum (and the optional sanctum.token_prefix).
• Only SHA-256({token}) is stored in personal_refresh_tokens.token; the column is hidden from serialization.
• PersonalRefreshToken::findToken() looks up the row by id, verifies the hash with hash_equals(), and only matches rows whose expires_at is in the future.
• Each refresh token is linked to the access token it was issued with (access_token_id); deleting the refresh token cascades to that access token via a model observer.
• The token's abilities (scope) are stored on the refresh token row, so refreshing preserves the scope even after the short-lived access token has been pruned.

Testing

A Docker setup is included to run the suite (including the PostgreSQL/MySQL matrix):

Changelog & License

See MIT license.