This package provides secure first factor one-time passwords (OTPs) for Laravel applications. Users enter their email and receive a one-time code to sign in—no passwords required.
- ✅ Session-locked - OTPs only work in the browser session that requested them
- ✅ Rate-limited - Configurable throttling with multi-tier limits
- ✅ Time-based expiration - Default 5 minutes, fully configurable
- ✅ Invalidated after first use - One-time use only
- ✅ Attempt limiting - Invalidated after 3 failed attempts
- ✅ Signed URLs - Cryptographic signature validation
- ✅ Detailed error messages - Clear feedback for users
- ✅ Customizable templates - Bring your own email design
- ✅ Auditable - Full event logging via Laravel events
OTPz works best with the official Laravel starter kits:
- React (Inertia.js)
- Vue (Inertia.js)
- Livewire (Volt)
OTPz's frontend components are designed to work out of the box with the Laravel starter kits and make use of their existing UI components (Button, Input, Label, etc.). Because these components are installed into your application you are free to customize them for any Laravel application using React, Vue, or Livewire.
composer require benbjurstrom/otpzphp artisan vendor:publish --tag="otpz-migrations"
php artisan migrate// app/Models/User.php
namespace App\Models;
use BenBjurstrom\Otpz\Models\Concerns\HasOtps;
use BenBjurstrom\Otpz\Models\Concerns\Otpable;
// ...
class User extends Authenticatable implements Otpable
{
use HasFactory, Notifiable, HasOtps;
// ...
}Choose your frontend framework:
php artisan vendor:publish --tag="otpz-react"This copies the following files to your application:
resources/js/pages/auth/otpz-login.tsx- Email entry pageresources/js/pages/auth/otpz-verify.tsx- OTP code entry pageapp/Http/Controllers/Auth/OtpzController.php- Self-contained controller handling all OTP logic
Note: These components import shadcn/ui components (
Button,Input,Label,Checkbox), layout components (AuthLayout), and use wayfinder for route generation from the Laravel React starter kit. If you're not using the starter kit, you may need to adjust these imports or create these components.
Add to routes/web.php:
use App\Http\Controllers\Auth\OtpzController;
Route::middleware('guest')->group(function () {
Route::get('otpz', [OtpzController::class, 'index'])
->name('otpz.index');
Route::post('otpz', [OtpzController::class, 'store'])
->name('otpz.store');
Route::get('otpz/{id}', [OtpzController::class, 'show'])
->name('otpz.show')
->middleware('signed');
Route::post('otpz/{id}', [OtpzController::class, 'verify'])
->name('otpz.verify')
->middleware('signed');
});That's it! The controller handles all the OTP logic for you.
php artisan vendor:publish --tag="otpz-vue"This copies the following files to your application:
resources/js/pages/auth/OtpzLogin.vue- Email entry pageresources/js/pages/auth/OtpzVerify.vue- OTP code entry pageapp/Http/Controllers/Auth/OtpzController.php- Self-contained controller handling all OTP logic
Note: These components import layout components (
AuthLayout), and use wayfinder for route generation from the Laravel Vue starter kit. If you're not using the starter kit, you may need to adjust these imports or create these components.
Add to routes/web.php:
use App\Http\Controllers\Auth\OtpzController;
Route::middleware('guest')->group(function () {
Route::get('otpz', [OtpzController::class, 'index'])
->name('otpz.index');
Route::post('otpz', [OtpzController::class, 'store'])
->name('otpz.store');
Route::get('otpz/{id}', [OtpzController::class, 'show'])
->name('otpz.show')
->middleware('signed');
Route::post('otpz/{id}', [OtpzController::class, 'verify'])
->name('otpz.verify')
->middleware('signed');
});That's it! The controller handles all the OTP logic for you.
php artisan vendor:publish --tag="otpz-livewire"This copies the following files to your application:
resources/views/livewire/auth/otpz-login.blade.php- Email entry pageresources/views/livewire/auth/otpz-verify.blade.php- OTP code entry pageapp/Http/Controllers/Auth/PostOtpController.php- Self-contained controller handling OTP verification
Note: These Volt components use Flux UI components and layout components from the Laravel Livewire starter kit. If you're not using the starter kit, you may need to adjust the component markup and styling.
Add to routes/web.php:
use App\Http\Controllers\Auth\PostOtpController;
use Livewire\Volt\Volt;
Route::middleware('guest')->group(function () {
Volt::route('otpz', 'auth.otpz-login')
->name('otpz.index');
Volt::route('otpz/{id}', 'auth.otpz-verify')
->middleware('signed')
->name('otpz.show');
Route::post('otpz/{id}', PostOtpController::class)
->middleware('signed')
->name('otpz.verify');
});The latest Laravel starter kits use Laravel Fortify for authentication. If you want to replace the default username/password login with OTPz:
For React:
In app/Providers/FortifyServiceProvider.php, update the loginView method:
Fortify::loginView(fn (Request $request) => Inertia::render('auth/otpz-login', []));For Vue:
In app/Providers/FortifyServiceProvider.php, update the loginView method:
Fortify::loginView(fn (Request $request) => Inertia::render('auth/OtpzLogin', []));For Livewire:
In app/Providers/FortifyServiceProvider.php, comment out the default login view:
// Fortify::loginView(fn () => view('livewire.auth.login'));Then in routes/web.php, update the OTPz route to use login:
Volt::route('login', 'auth.otpz-login')
->name('login'); // Changed path and name from 'otpz'Now when users visit /login or are redirected to the login page, they'll see the OTPz email entry form instead of the traditional username/password form.
php artisan vendor:publish --tag="otpz-config"This is the contents of the published config file:
<?php
return [
/*
|--------------------------------------------------------------------------
| Expiration and Throttling
|--------------------------------------------------------------------------
|
| These settings control the security aspects of the generated codes,
| including their expiration time and the throttling mechanism to prevent
| abuse.
|
*/
'expiration' => 5, // Minutes
'limits' => [
['limit' => 1, 'minutes' => 1],
['limit' => 3, 'minutes' => 5],
['limit' => 5, 'minutes' => 30],
],
/*
|--------------------------------------------------------------------------
| Model Configuration
|--------------------------------------------------------------------------
|
| This setting determines the model used by Otpz to store and retrieve
| one-time passwords. By default, it uses the 'App\Models\User' model.
|
*/
'models' => [
'authenticatable' => App\Models\User::class,
],
/*
|--------------------------------------------------------------------------
| Mailable Configuration
|--------------------------------------------------------------------------
|
| This setting determines the Mailable class used by Otpz to send emails.
| Change this to your own Mailable class if you want to customize the email
| sending behavior.
|
*/
'mailable' => BenBjurstrom\Otpz\Mail\OtpzMail::class,
/*
|--------------------------------------------------------------------------
| Template Configuration
|--------------------------------------------------------------------------
|
| This setting determines the email template used by Otpz to send emails.
| Switch to 'otpz::mail.notification' if you prefer to use the default
| Laravel notification template.
|
*/
'template' => 'otpz::mail.otpz',
// 'template' => 'otpz::mail.notification',
/*
|--------------------------------------------------------------------------
| User Resolver
|--------------------------------------------------------------------------
|
| Defines the class responsible for finding or creating users by email address.
| The default implementation will create a new user when an email doesn't exist.
| Replace with your own implementation for custom user resolution logic.
|
*/
'user_resolver' => BenBjurstrom\Otpz\Actions\GetUserFromEmail::class,
];php artisan vendor:publish --tag="otpz-translations"This package publishes the translations file:
lang/
└── vendor/
└── en
└── otp.php (standart translations)Publish the email templates to customize styling:
php artisan vendor:publish --tag="otpz-views"This publishes:
resources/views/vendor/otpz/
├── mail/
│ ├── otpz.blade.php # Custom styled template
│ └── notification.blade.php # Laravel notification template
└── components/
└── template.blade.php
Switch between templates in config/otpz.php:
'template' => 'otpz::mail.notification', // Use Laravel's default stylingBy default, OTPz creates new users when an email doesn't exist. You can customize this behavior by creating your own user resolver and registering it in the config. In this example we throw a validation error if a user with the given email address does not exist.
namespace App\Actions;
use App\Models\User;
use BenBjurstrom\Otpz\Models\Concerns\Otpable;
use Illuminate\Validation\ValidationException;
class MyUserResolver
{
public function handle(string $email): Otpable
{
$user = User::where('email', $email)->first();
if($user){
return $user;
}
throw ValidationException::withMessages([
'email' => 'No user found with that email address.',
]);
}
}Update config/otpz.php:
'user_resolver' => App\Actions\MyUserResolver::class,composer testPlease see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.