whilesmart / laravel-user-authentication

v1.1.0 2026-09-22 20:32 UTC

Requires

• php: ^8.3
• kreait/laravel-firebase: ^6.1
• laravel/sanctum: ^4.1
• laravel/socialite: ^5.23
• socialiteproviders/apple: ^5.8

Requires (Dev)

• fakerphp/faker: ^1.24
• larastan/larastan: ^3.0
• laravel/pint: ^1.22
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^10.4
• phpmd/phpmd: @stable
• phpstan/phpstan: ^2.1
• smartpings/php-sdk: dev-main
• squizlabs/php_codesniffer: ^4.0
• zircote/swagger-php: ^5.1

Suggests

• smartpings/php-sdk: Install this when verification.provider is set to smartpings.

MIT

• WhileSmart

Published on Packagist.org on 2026-09-22 20:32 UTC

README

Authentication endpoints for Laravel APIs. Users register and sign in with a password, OAuth, Firebase or a passkey, and receive a Sanctum access token once any second factor is checked. Install the package and run its migrations to enable the routes.

What you get

Area	Included
Accounts	Registration, login by email, phone or username, logout, password reset by code
Email sign-in	Optional passwordless sign-in with an emailed code or magic link
Social sign-in	Socialite drivers (Google, Apple and others) and Firebase ID tokens
Passkeys	WebAuthn registration and login, with optional discoverable credentials
Two-factor	TOTP apps, email and SMS codes, magic links, recovery codes, several labeled factors per user
Verification	Email or phone verification before registration, sent by your own listeners or by SmartPings
Integration	Events, before and after hooks, a swappable response format, OpenAPI attributes

Install

Requires PHP 8.3 or later and Laravel Sanctum.

composer require whilesmart/laravel-user-authentication
php artisan migrate

The service provider registers itself and loads its routes under /api. Change the prefix with USER_AUTH_ROUTE_PREFIX. The installation guide covers publishing the config, migrations, routes and controllers.

How sign-in works

A user without a second factor gets an access token straight away:

POST /api/login
{"email": "[e-mail]", "password": "secret-password"}

{
  "success": true,
  "message": "User successfully logged in",
  "data": {
    "token": "1|abc...",
    "token_type": "Bearer",
    "user": {"id": 1, "email": "[e-mail]"}
  }
}

A user with a confirmed second factor gets a pending two-factor token instead of an access token:

{
  "success": true,
  "message": "Two-factor authentication required.",
  "data": {
    "two_factor_required": true,
    "factor_id": 1,
    "method": "totp",
    "two_factor_token": "<pending-token>",
    "factors": [{"id": 1, "type": "totp", "label": "Phone"}]
  }
}

Send two_factor_token and a code to POST /api/2fa/verify to receive an access token. Protect your own routes with ['auth:sanctum', 'two-factor'] so tokens that skipped the second factor are refused. The two-factor guide covers enrollment, resending, magic links and recovery codes.

Configuration

Most settings read an environment variable. The ones most installs touch:

Variable	Default	Purpose
USER_AUTH_ROUTE_PREFIX	api	Prefix for every package route
USER_AUTH_REQUIRE_EMAIL_VERIFICATION	false	Require a verified email before registration
USER_AUTH_REQUIRE_PHONE_VERIFICATION	false	Require a verified phone before registration
USER_AUTH_VERIFICATION_PROVIDER	default	default or smartpings
USER_AUTH_SELF_MANAGED	true	Set to false to let SmartPings send and check codes
USER_AUTH_MAGIC_LINK_URL	none	Frontend page that receives two-factor magic links
USER_AUTH_EMAIL_LOGIN_ENABLED	false	Turn on passwordless email sign-in
USER_AUTH_EMAIL_LOGIN_CREATE_USERS	false	Create an account for an unknown email on sign-in
USER_AUTH_EMAIL_LOGIN_URL	none	Frontend page that receives email sign-in links
USER_AUTH_PASSKEY_DOMAIN	none	Domain that identifies your app to passkeys, as a hostname or URL
USER_AUTH_PASSKEY_ALLOWED_ORIGINS	none	Frontend origins allowed to register and use passkeys

The full list, with rate limits and expiry times, is in config/user-authentication.php and the guides below.

Two-factor challenges expire but stay in the database until pruned. Schedule pruning in your application:

use Illuminate\Support\Facades\Schedule;
use Whilesmart\UserAuthentication\Models\AuthChallenge;

Schedule::command('model:prune', ['--model' => [AuthChallenge::class]])->daily();

Custom user model

Set user_model in the config. Add HasApiTokens, HasPasskeys and HasTwoFactorAuth to your model. The two-factor middleware requires HasTwoFactorAuth.

use Laravel\Sanctum\HasApiTokens;
use Whilesmart\UserAuthentication\Traits\HasPasskeys;
use Whilesmart\UserAuthentication\Traits\HasTwoFactorAuth;

class User extends Authenticatable
{
    use HasApiTokens, HasPasskeys, HasTwoFactorAuth;
}

Endpoints

All paths use the default /api prefix.

Method	Path	Notes
POST	/register
POST	/login	Email, phone or username with a password
POST	/login/email	Sends a code, plus a link when a URL is set; returns 202
POST	/login/email/verify	{email, code} or {token}
POST	/logout	Signed in
POST	/send-verification-code
POST	/verify-code
POST	/password/reset-code
POST	/password/reset
GET	/oauth/{driver}/login
GET POST	/oauth/{driver}/callback
POST	/oauth/firebase/{driver}/callback	See kreait/laravel-firebase for setup
POST	/passkeys/login/options
POST	/passkeys/login
POST	/passkeys/register/options	Signed in
POST	/passkeys/register	Signed in
GET	/passkeys	Signed in
DELETE	/passkeys/{id}	Signed in
POST	/2fa/verify	Pending token and code
POST	/2fa/resend	Pending token and factor
POST	/2fa/verify-link	Pending token and magic link token
GET	/2fa/factors	Signed in
POST	/2fa/setup	Signed in
POST	/2fa/confirm	Signed in
POST	/2fa/disable	Signed in
POST	/2fa/recovery-codes	Signed in

"Signed in" routes use auth:sanctum and two-factor. Sending verification and password reset codes, passkey sign-in and registration, and every two-factor route except /2fa/factors are rate limited.

Events

Listen to these to send mail and SMS, write audit logs or sync other systems:

Event	Fired when
UserRegisteredEvent	A user registers
UserLoggedInEvent	A sign-in completes, including after the second factor
UserLoggedOutEvent	A user logs out
OauthUserAuthenticatedEvent	An OAuth or Firebase sign-in resolves a user
VerificationCodeGeneratedEvent	A verification or two-factor code is created; carries the magic link when there is one
PasswordResetCodeGeneratedEvent	A password reset code is created
PasswordResetCompleteEvent	A password is reset

Apple sign-in

Apple sign-in comes from Socialite Providers. Follow their Apple setup, then use apple as the driver.

OpenAPI

Publish the documentation class so your OpenAPI generator picks up the endpoints:

php artisan vendor:publish --tag=laravel-user-authentication-docs

This creates app/Http/Documentation/UserAuthOpenApiDocs.php.

Guides

Guide	Covers
Installation	Setup and publishing
Verification	Email and phone verification with your provider or SmartPings
Email sign-in	Codes, links, account creation and delivery events
Passkeys	WebAuthn settings and troubleshooting
Two-factor authentication	Factors, challenges, magic links, recovery codes
Customization	Response format, middleware hooks

The same guides are published at developers.whilesmart.com.

Development

make setup      # start the containers, install dependencies, run the tests
composer test   # PHPUnit through Orchestra Testbench
composer lint   # Laravel Pint
composer phpstan
composer phpmd

License

MIT. See LICENSE.