README

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):

Key	Env	Default	Description
`require_email_verification`	`AUTH_REQUIRE_EMAIL_VERIFICATION`	`true`	Block protected routes until email verified
`remember_me_expiration_days`	`AUTH_REMEMBER_ME_EXPIRATION_DAYS`	`5`	Session duration when "remember me" checked
`password_reset_token_expiration_minutes`	`AUTH_PASSWORD_RESET_EXPIRATION_MINUTES`	`60`	Password reset link validity
`email_verification_expire_minutes`	`AUTH_EMAIL_VERIFICATION_EXPIRE_MINUTES`	`60`	Verification link validity
`frontend_reset_password_url`	`FRONTEND_RESET_PASSWORD_URL`	`APP_URL`	Base URL for reset link
`route_prefix`	`AUTH_API_SANCTUM_ROUTE_PREFIX`	`''`	Prefix for auth routes
`api_rate_limit`	`AUTH_API_RATE_LIMIT`	`60`	Requests per minute for API

API Endpoints

Method	Route	Auth	Description
POST	`/sanctum/csrf-cookie`	No	Get CSRF cookie (call before login)
POST	`/register`	No	Create user, optional verification email
POST	`/login`	No	Authenticate, returns user
POST	`/logout`	Yes	Invalidate session
GET	`/me`	Yes	Current user (requires verified email if enabled)
POST	`/forgot-password`	No	Send reset email
POST	`/reset-password`	No	Reset password with token
GET	`/email/verify/{id}/{hash}`	No	Verify email via signed link

Testing

composer test

Changelog

See CHANGELOG for recent changes.

License

MIT. See LICENSE.

listradigital / laravel-auth-api-sanctum

Maintainers

Package info

Statistics

Security