README

API-first authentication package that extends Laravel Fortify with JSON responses, OAuth support, and enhanced features. Uses Fortify 1:1 with minimal overrides via container bindings.

Philosophy

This package wraps Laravel Fortify with quality-of-life improvements:

• API-First Responses - Returns JSON with user data instead of redirects
• OAuth/Socialite Integration - Social login with secure nonce-based flow
• Zero Configuration - Auto-discovers and binds overrides via service provider
• Fortify Compatible - Use standard config/fortify.php to enable/disable features

Installation

1. Install Fortify and Sanctum

composer require laravel/fortify laravel/sanctum laravel/socialite
php artisan fortify:install
php artisan sanctum:install
php artisan migrate

2. Install Quvel Auth

composer require quvel/auth

That's it. The package auto-discovers and registers its service provider.

3. Configure Fortify

Edit config/fortify.php:

'prefix' => 'auth', // Routes at /auth/*
'views' => false, // API-only mode

'features' => [
 Features::registration(),
 Features::resetPasswords(),
 // Features::emailVerification(),
 Features::updateProfileInformation(),
 Features::updatePasswords(),
 Features::twoFactorAuthentication([
 'confirm' => true,
 'confirmPassword' => true,
 ]),
],

4. Publish Migrations (Optional)

php artisan vendor:publish --tag=quvel-auth-migrations
php artisan migrate

How It Works

Quvel Auth uses Laravel's container to override Fortify's default implementations:

// Our AuthServiceProvider automatically binds these:

// Fortify uses our custom CreateNewUser action
$app->singleton(CreatesNewUsers::class, CreateNewUser::class);

// Fortify uses our JSON LoginResponse instead of redirects
$app->singleton(LoginResponseContract::class, LoginResponse::class);

// etc.

When Fortify's controllers run, they resolve these contracts from the container and get our implementations. No route overrides needed.

Routes

Fortify provides core routes (login, register), we provide the rest:

# Fortify Routes (using our container bindings)
POST /auth/login → JSON with user data
POST /auth/register → JSON with user data

# Our Custom Routes
GET /auth/session → Current session info
POST /auth/logout → Logout response

# Password Management
POST /auth/forgot-password
POST /auth/reset-password

# Two-Factor Authentication
POST /auth/two-factor-challenge
POST /auth/user/two-factor-authentication → Enable 2FA
DELETE /auth/user/two-factor-authentication → Disable 2FA
GET /auth/user/two-factor-qr-code
GET /auth/user/two-factor-recovery-codes
POST /auth/user/two-factor-recovery-codes → Regenerate codes

# Profile Management
PUT /auth/user/profile-information
PUT /auth/user/password

# OAuth (Socialite)
GET /auth/provider/{provider}/redirect
GET /auth/provider/{provider}/callback
POST /auth/provider/{provider}/create-nonce
POST /auth/provider/{provider}/redeem-nonce

API Responses

All responses are JSON with consistent structure:

Login Success (no 2FA):

{
 "message": "Login successful",
 "user": { "id": 1, "name": "...", "email": "..." },
 "two_factor": false
}

Login Requires 2FA:

{
 "message": "Two-factor authentication required",
 "two_factor": true
}

Registration:

{
 "message": "Registration successful",
 "user": { "id": 1, "name": "...", "email": "..." }
}

Configuration

Fortify Features

Enable/disable features in config/fortify.php:

'features' => [
 Features::registration(), // POST /auth/register
 Features::resetPasswords(), // POST /auth/forgot-password, etc.
 Features::emailVerification(), // Email verification routes
 Features::updateProfileInformation(), // PUT /auth/user/profile-information
 Features::updatePasswords(), // PUT /auth/user/password
 Features::twoFactorAuthentication(), // All 2FA routes
],

Socialite (OAuth)

Configure providers in config/services.php:

'google' => [
 'client_id' => env('GOOGLE_CLIENT_ID'),
 'client_secret' => env('GOOGLE_CLIENT_SECRET'),
 'redirect' => env('GOOGLE_REDIRECT_URI'),
],

Disable OAuth in config/quvel-auth.php:

'socialite' => [
 'enabled' => false,
],

Rate Limiting

Automatically configured (5 requests/minute for login and 2FA). Override in your AppServiceProvider if needed:

use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('login', fn ($request) =>
 Limit::perMinute(10)->by($request->email . $request->ip())
);

Customization

Override Response Classes

Create your own response:

// app/Http/Responses/CustomLoginResponse.php
class CustomLoginResponse implements LoginResponseContract
{
 public function toResponse($request): JsonResponse
 {
 return response()->json([
 'user' => $request->user()->load('roles'),
 'permissions' => $request->user()->getAllPermissions(),
 ]);
 }
}

Bind in your AppServiceProvider:

$this->app->singleton(
 \Laravel\Fortify\Contracts\LoginResponse::class,
 \App\Http\Responses\CustomLoginResponse::class
);

Override Actions

Same pattern for actions:

$this->app->singleton(
 \Laravel\Fortify\Contracts\CreatesNewUsers::class,
 \App\Actions\Fortify\CreateNewUser::class
);

Advanced: Publish Routes

For full route customization:

php artisan vendor:publish --tag=quvel-auth-routes

Then disable package routes in config/quvel-auth.php:

'routes' => [
 'enabled' => false,
],

Troubleshooting

Routes not showing?

php artisan route:list --path=auth

Check that Fortify features are enabled and views => false.

Rate limiter errors? Clear config cache:

php artisan config:clear

Need to customize? Check AuthServiceProvider@registerFortifyOverrides() to see all container bindings.

License

MIT