How to Use Laravel Sanctum for API Authentication

To use Laravel Sanctum, install the package, run migrations, and add the HasApiTokens trait to your User model. Then, protect routes with the auth:sanctum middleware and issue tokens using createToken() method for API authentication.

Syntax

Laravel Sanctum uses these main parts:

• HasApiTokens trait: Add to User model to enable token abilities.
• auth:sanctum middleware: Protect routes to require valid tokens.
• createToken('token-name'): Generate API tokens for users.

php

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;
}

// Protect routes in routes/api.php
Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

Example

This example shows how to set up Sanctum, create a token, and protect an API route.

php

<?php

// 1. Install Sanctum via Composer
// composer require laravel/sanctum

// 2. Publish and run migrations
// php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
// php artisan migrate

// 3. Add HasApiTokens trait to User model
namespace App\Models;

use Laravel\Sanctum\HasApiTokens;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasApiTokens;
}

// 4. Issue token in a controller or route
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use App\Models\User;

Route::post('/login', function (Request $request) {
    $user = User::where('email', $request->email)->first();

    if (! $user || ! Hash::check($request->password, $user->password)) {
        return response()->json(['message' => 'Invalid credentials'], 401);
    }

    $token = $user->createToken('api-token')->plainTextToken;

    return response()->json(['token' => $token]);
});

// 5. Protect routes
Route::middleware('auth:sanctum')->get('/profile', function (Request $request) {
    return $request->user();
});

Output

{"token":"<generated_token_string>"}

Common Pitfalls

Common mistakes when using Laravel Sanctum include:

• Not adding HasApiTokens trait to the User model, so tokens can't be created.
• Forgetting to run Sanctum migrations, causing database errors.
• Not protecting API routes with auth:sanctum middleware, leaving endpoints unprotected.
• Using session-based authentication routes without configuring Sanctum for SPA or API tokens properly.

php

<?php
// Wrong: Missing HasApiTokens trait
class User extends Authenticatable
{
    // use HasApiTokens; // This line is missing
}

// Right: Add HasApiTokens trait
class User extends Authenticatable
{
    use HasApiTokens;
}

// Wrong: Route without middleware
Route::get('/profile', function (Request $request) {
    return $request->user();
});

// Right: Route with auth:sanctum middleware
Route::middleware('auth:sanctum')->get('/profile', function (Request $request) {
    return $request->user();
});

Quick Reference

• Install Sanctum: composer require laravel/sanctum
• Publish & migrate: php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider" and php artisan migrate
• User model: Add use HasApiTokens;
• Protect routes: Use auth:sanctum middleware
• Create token: $user->createToken('token-name')->plainTextToken

Key Takeaways

Add HasApiTokens trait to your User model to enable token creation.

Protect API routes with auth:sanctum middleware to require valid tokens.

Run Sanctum migrations after installation to create necessary tables.

Use createToken() method on User to generate API tokens for authentication.

Check credentials carefully before issuing tokens to users.