Auth for Laravel — headless multi-guard login with 2FA, passkeys and JWT sessions

Andrej Mihaliak — Mon, 05 Oct 2026 09:15:02 +0000

Every API-backed Laravel app we built needed sign-in, and the hand-written version kept having the same small gaps: a login error that told you whether an email was registered, a password reset that left old sessions alive, a two-factor step a client could skip. Each one is minor. Together they are how accounts get taken over. So we pulled all of it into one package and open-sourced it.

What it does

Auth for Laravel is headless account authentication for Laravel apps behind a mobile app or a single-page frontend. It owns the policy and orchestration; your app keeps its screens.

Four ways to sign in: password, magic link, email code and passkey.
A challenge engine for the second step (authenticator code, backup code or passkey), including forced enrolment when a guard requires two-factor.
RS256 access tokens with rotating refresh tokens, and device sessions a user can end one by one, all others, or everywhere.
Registration, invitations, email verification, email change and password resets.
A login-activity log, throttling, new-device alerts and a hook for your own risk rules.
Separate guards (users, clients, staff), each with its own model, config, endpoints, JWT audience and sessions.
Opt-in JSON endpoints and an event for every state change.

Installation

composer require roundly-consulting/auth-for-laravel
php artisan jwt:generate-keys
php artisan authentication:install   # publishes config + migrations, prints the guard wiring
php artisan migrate

authentication:install prints the config/auth.php guard wiring instead of editing your config, and php artisan authentication:check tells you what is still wrong.

Usage

Give the guard's model the contracts of the features it uses:

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use RoundlyConsulting\Auth\Concerns\HasAuthentication;
use RoundlyConsulting\Auth\Contracts\Account;
use RoundlyConsulting\Passkeys\Concerns\InteractsWithPasskeys;
use RoundlyConsulting\Passkeys\Contracts\HasPasskeys;
use RoundlyConsulting\RefreshTokens\Traits\HasRefreshTokens;
use RoundlyConsulting\TwoFactor\Concerns\HasTwoFactorAuthentication;
use RoundlyConsulting\TwoFactor\Contracts\TwoFactorAuthenticatable;

class User extends Authenticatable implements Account, HasPasskeys, TwoFactorAuthenticatable
{
    use HasAuthentication, HasRefreshTokens, HasTwoFactorAuthentication, InteractsWithPasskeys, Notifiable;

    protected function casts(): array
    {
        return [...$this->authenticationCasts(), ...$this->twoFactorCasts(), 'email_verified_at' => 'datetime'];
    }
}

use RoundlyConsulting\Auth\DataTransferObjects\PasswordCredentials;
use RoundlyConsulting\Auth\Facades\Authentication;
use RoundlyConsulting\Auth\Http\Resources\ChallengeResource;
use RoundlyConsulting\Auth\Http\Resources\TokenPairResource;

$guard = Authentication::guard('users');

$result = $guard->attempt(
    new PasswordCredentials(identifier: $request->string('email')->toString(), password: $request->string('password')->toString()),
    $guard->contextFrom($request),
);

return $result->isAuthenticated()
    ? TokenPairResource::make($result->tokens)
    : ChallengeResource::make($result->challenge);   // continue with $guard->challenges()->complete(…)

Rotate the refresh token, or sign the account out of every device:

$tokens = $guard->refresh($refreshToken, $guard->contextFrom($request));   // the old access token stops working

$guard->logoutEverywhere($user);

Finishing the second step

When a login returns a challenge, the client sends the code back and you complete it on the same guard. Backup codes and passkeys go through the same complete() call.

use RoundlyConsulting\Auth\DataTransferObjects\ChallengeFactorData;
use RoundlyConsulting\Auth\Enums\FactorMethod;

$context = $guard->contextFrom($request);

if ($result->requiresChallenge()) {
    $pending = $result->challenge;   // token, expiresAt, method, completed, remaining (ChallengeRequirement[]), attemptsLeft
    // … later, with the user's TOTP code:
    $result = $guard->challenges()->complete(new ChallengeFactorData(
        challengeToken: $pending->token,
        method: FactorMethod::Totp,
        context: $context,
        code: $request->input('code'),
    ));
}

Challenges are single-use and stored in the database, and each code attempt is counted before the code is checked, so parallel guesses get no extra tries.

Endpoints, per guard

The JSON endpoints are off until you switch them on, either with routes.enabled or explicitly:

// routes/api.php
Authentication::routes('users');                                      // defaults

Authentication::routes('clients')
    ->prefix('api/clients/auth')
    ->name('clients.auth.')
    ->middleware(['api'])
    ->authenticatedMiddleware(['authentication.active'])
    ->except(['registration', 'invitations.manage']);

A route exists only while its feature is enabled for that guard.

More than one kind of account

Scaffold a guard (model, migration, factory), then check it:

php artisan authentication:guard staff --model=StaffMember --no-passkeys
php artisan authentication:check staff

Guards share nothing: a users token on a clients route is a 401 even for the same primary key. Two-factor, passkeys, registration mode (open, invite-only or closed), verification and password rules are all set per guard.

Defaults we cared about

Password login, magic-link and email-code requests, and forgot password all answer the same way whether or not the address is registered.
Throttles take the attempt before the password is hashed, so concurrent guesses are all counted.
Emailed links and codes, invitations and challenges are single-use and stored only as keyed HMAC hashes.
By default a password, email or two-factor change ends the other sessions; the device that made the change gets a fresh token pair back.
Reusing a rotated refresh token kills that session and alerts the owner.

Testing

There is no Authentication::fake(), on purpose: the InteractsWithAuthentication helpers issue a real token pair, so tests hit the real guard, audience, denylist and token-version checks:

$this->actingAsAccount($user, 'users', [AuthMethodReference::Pwd]);   // a REAL token pair as the bearer
$this->assertLoginActivity('users', ActivityType::PasswordLogin, ActivityOutcome::Succeeded);
$this->assertTokensInvalidated($user, InvalidationReason::PasswordChanged);   // moved since actingAsAccount() (or pass `since:`)

Every write also fires an event, so Event::fake() covers the rest.

Social login and SSO

Neither ships in the package, but your existing SSO callback can vouch for the user and get the same token pair as any other login:

// SSO callback: the host vouches for the authentication
$pair = Authentication::guard('users')->issueTokens($user, $context, LoginMethod::Host, [AuthMethodReference::Mfa]);

Requirements

PHP ^8.4 (ext-bcmath, ext-mbstring, ext-openssl), Laravel 12 or 13, a cache store with atomic locks and a mail transport. MIT licensed. Runtime dependencies are only Laravel, Symfony and other Roundly packages, which Composer pulls in.

DEV Community: Andrej Mihaliak