Authentication Events Reference

Every stage of the authentication lifecycle dispatches events you can listen to for auditing, SIEM attribution, side effects, and real-time monitoring. The package fires Laravel’s standard auth events so your existing listeners keep working, and adds custom events for the contextual concepts — principal assignment, device binding, and refresh rotation — that Laravel’s built-in events do not cover.

Standard Laravel events

These events are dispatched on both the JWT bearer and HTTP Basic paths:

Event	Fired when
`Illuminate\Auth\Events\Attempting`	Bearer, refresh, or credential attempt starts
`Illuminate\Auth\Events\Validated`	Successful login path about to bind context
`Illuminate\Auth\Events\Authenticated`	Identity bound to the guard
`Illuminate\Auth\Events\Login`	Full lifecycle complete
`Illuminate\Auth\Events\Failed`	Any bearer, refresh, or credential rejection

Custom events

Event	Fired when
`SineMacula\Laravel\Authentication\Events\PrincipalAssigned`	Principal resolved and bound to the guard
`SineMacula\Laravel\Authentication\Events\DeviceAuthenticated`	Device hydrated and bound to the guard
`SineMacula\Laravel\Authentication\Events\Refreshed`	Refresh exchange completed successfully
`SineMacula\Laravel\Authentication\Events\RefreshFailed`	Refresh exchange failed

`PrincipalAssigned`

Dispatched immediately after the principal resolver binds a principal to a guard. Carries the guard name and the resolved principal instance.

use SineMacula\Laravel\Authentication\Events\PrincipalAssigned;

public function handle(PrincipalAssigned $event): void
{
    // $event->guard     — the guard name (e.g. 'api')
    // $event->principal — the resolved Principal instance
}

`DeviceAuthenticated`

Dispatched when a device is hydrated from the devices table and bound to the guard during a bearer or refresh request. Carries the guard name and the device instance. Listeners on this event may persist request metadata — such as last IP address or user-agent — during the authentication lifecycle.

use SineMacula\Laravel\Authentication\Events\DeviceAuthenticated;

public function handle(DeviceAuthenticated $event): void
{
    // $event->guard  — the guard name
    // $event->device — the authenticated Device instance

    $event->device->update([
        'last_ip'         => request()->ip(),
        'last_user_agent' => request()->userAgent(),
    ]);
}

`Refreshed`

Dispatched after a successful refresh-token exchange. Implements ShouldDispatchAfterCommit, so it fires only after the rotation database transaction commits. Carries the full contextual surface so activity-log consumers can attribute the refresh without a second round-trip through the guard.

use SineMacula\Laravel\Authentication\Events\Refreshed;

public function handle(Refreshed $event): void
{
    // $event->guard     — the guard name
    // $event->identity  — the Identity whose session was refreshed
    // $event->principal — the Principal bound on the refreshed guard
    // $event->device    — the Device whose rotation key was rotated
}

`RefreshFailed`

Dispatched whenever a refresh-token exchange fails. Carries a RefreshFailureReason backed enum so SIEM consumers can count and alert on failure modes without scraping log messages.

use SineMacula\Laravel\Authentication\Events\RefreshFailed;
use SineMacula\Laravel\Authentication\Events\Enums\RefreshFailureReason;

public function handle(RefreshFailed $event): void
{
    // $event->guard    — the guard name
    // $event->reason   — a RefreshFailureReason enum case
    // $event->deviceId — device ID from the token, when parseable; null otherwise

    if ($event->reason === RefreshFailureReason::ROTATION_REUSE) {
        // Concurrent rotation or replay detected — device has been revoked.
        // Consider alerting your security team.
    }
}

`RefreshFailureReason` reason codes

RefreshFailed carries a RefreshFailureReason backed enum. Every failure path dispatches a distinct reason code so you can attribute events without ambiguity:

Reason	Value	Meaning
`TOKEN_INVALID`	`token_invalid`	Decode, expiry, `typ`, `iss`, or `aud` failure — the refresh token itself is malformed or expired
`DEVICE_UNKNOWN`	`device_unknown`	The device ID in the token did not resolve to a record in the `devices` table
`ROTATION_MISMATCH`	`rotation_mismatch`	The rotation digest did not match the stored refresh key — stale or tampered token
`ROTATION_REUSE`	`rotation_reuse`	Replay or concurrent rotation detected; the device has been revoked to prevent further use
`DEVICE_REVOKED`	`device_revoked`	The device row was explicitly marked as revoked before the refresh attempt
`AUTHENTICATABLE_MISSING`	`authenticatable_missing`	The device’s `authenticatable` polymorphic relation could not be loaded
`IDENTITY_INACTIVE`	`identity_inactive`	The resolved identity implements `CanBeActive` and returned `false`
`PRINCIPAL_UNRESOLVED`	`principal_unresolved`	The principal resolver returned `null` for the identity
`PRINCIPAL_MISMATCH`	`principal_mismatch`	The resolved principal does not match the `pid` hint carried in the refresh token
`PRINCIPAL_INACTIVE`	`principal_inactive`	The resolved principal implements `CanBeActive` and returned `false`

Listening to events

use Illuminate\Support\Facades\Event;
use SineMacula\Laravel\Authentication\Events\RefreshFailed;
use SineMacula\Laravel\Authentication\Events\Refreshed;
use SineMacula\Laravel\Authentication\Events\PrincipalAssigned;
use SineMacula\Laravel\Authentication\Events\DeviceAuthenticated;

// In AppServiceProvider::boot() or EventServiceProvider::$listen:
Event::listen(RefreshFailed::class, [RefreshAuditListener::class, 'handle']);
Event::listen(Refreshed::class, [RefreshAuditListener::class, 'handleSuccess']);
Event::listen(PrincipalAssigned::class, [PrincipalAuditListener::class, 'handle']);
Event::listen(DeviceAuthenticated::class, [DeviceMetadataListener::class, 'handle']);

Or using the attribute syntax available in Laravel 11+:

use Illuminate\Events\Attributes\AsEventListener;
use SineMacula\Laravel\Authentication\Events\RefreshFailed;

#[AsEventListener]
final class RefreshAuditListener
{
    public function handle(RefreshFailed $event): void
    {
        // ...
    }
}

Get Started

Core Concepts

Configuration

Guides

Events & Security

Standard Laravel events

Custom events

`PrincipalAssigned`

`DeviceAuthenticated`

`Refreshed`

`RefreshFailed`

`RefreshFailureReason` reason codes

Listening to events

​Standard Laravel events

​Custom events

​PrincipalAssigned

​DeviceAuthenticated

​Refreshed

​RefreshFailed

​RefreshFailureReason reason codes

​Listening to events

Standard Laravel events

Custom events

`PrincipalAssigned`

`DeviceAuthenticated`

`Refreshed`

`RefreshFailed`

`RefreshFailureReason` reason codes

Listening to events