Laravel Auth API Sanctum

SPA-ready authentication API for Laravel with Sanctum. Provides register, login, logout, email verification, password reset, and a protected /me endpoint—all configurable and using httpOnly cookies for security.

Installation

composer require tilistra/laravel-auth-api-sanctum

Publish the config file:

php artisan vendor:publish --tag="laravel-auth-api-sanctum-config"

Publish pt-BR translations (validation and passwords) for 422 error messages:

php artisan vendor:publish --tag=lang

Then set config('app.locale') to pt_BR in your application.

Publish package documentation into your app under docs/packages/{vendor}/{package}/{installed-version}/:

php artisan vendor:publish --tag=laravel-auth-api-sanctum-docs

Publish and run Sanctum migrations:

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

User Model Setup

Your User model must implement MustVerifyEmail and use HasApiTokens, Notifiable. Override the notification methods to use the package's queued notifications:

use AuthApiSanctum\Concerns\HasAuthApiSanctumNotifications;
use Illuminate\Contracts\Auth\MustVerifyEmail;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable implements MustVerifyEmail
{
    use HasApiTokens, HasAuthApiSanctumNotifications, HasFactory, Notifiable;
    // ...
}

Or manually override:

public function sendEmailVerificationNotification(): void
{
    $this->notify(new \AuthApiSanctum\Notifications\VerifyEmailQueued);
}

public function sendPasswordResetNotification($token): void
{
    $this->notify(new \AuthApiSanctum\Notifications\ResetPasswordQueued($token));
}

Bootstrap Configuration (Laravel 11+)

In bootstrap/app.php, ensure stateful API and throttle are enabled:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->statefulApi();
    $middleware->throttleApi();
    $middleware->alias([
        'verified.email' => \AuthApiSanctum\Http\Middleware\EnsureEmailIsVerifiedConfigurable::class,
    ]);
})

Exception Handlers (401, 403, 404, 500)

To return empty body for 401, 403, 404, 500 etc. on auth API routes (RF-4, RF-5), configure your application's exception handler. Use AuthApiSanctum::isAuthApiRequest() to detect requests targeting this package's routes:

// In bootstrap/app.php (Laravel 11+) or App\Exceptions\Handler
use AuthApiSanctum\AuthApiSanctum;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Http\Request;
use Illuminate\Foundation\Configuration\Exceptions;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->render(function (AuthenticationException $e, Request $request) {
        if (AuthApiSanctum::isAuthApiRequest($request)) {
            return response('', 401);
        }
    });

    $exceptions->render(function (AccessDeniedHttpException $e, Request $request) {
        if (AuthApiSanctum::isAuthApiRequest($request)) {
            return response('', 403);
        }
    });

    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if (AuthApiSanctum::isAuthApiRequest($request)) {
            return response('', 404);
        }
    });

    // For 500 and other HTTP errors, check if exception has getStatusCode()
    $exceptions->render(function (Throwable $e, Request $request) {
        if (! AuthApiSanctum::isAuthApiRequest($request)) {
            return null;
        }
        $status = method_exists($e, 'getStatusCode') ? $e->getStatusCode() : 500;
        return response('', $status);
    });
})

For Laravel 10 or custom Handler, use the renderable method with the same logic. The package already customizes 422 (validation) to return {"errors": {...}} without message.

Auth Config Integration

In config/auth.php, use the package values for password reset and email verification expiry:

'passwords' => [
    'users' => [
        'provider' => 'users',
        'table' => 'password_reset_tokens',
        'expire' => config('auth_api_sanctum.password_reset_token_expiration_minutes', 60),
        'throttle' => 60,
    ],
],
'verification' => [
    'expire' => config('auth_api_sanctum.email_verification_expire_minutes', 60),
],

CORS

Ensure config/cors.php allows credentials for your SPA origin:

'supports_credentials' => true,
'allowed_origins' => [env('FRONTEND_URL', 'http://localhost:3000')],

Configuration

Published config (config/auth_api_sanctum.php):

API Endpoints

Testing

composer test

Changelog

See CHANGELOG for recent changes.

License

MIT. See LICENSE.