Laravel Sanctum — احراز هویت API با Token (راهنمای کامل)

وقتی اپ موبایل یا SPA جدا از Laravel backend دارید، session cookie کافی نیست — Sanctum token-based auth سبک و رسمی Laravel است. برخلاف Passport (OAuth2 سنگین)، Sanctum برای first-party API ایده‌آل است. در پروژه‌های فروشگاه و پورتال من Sanctum را برای اپ اندروید و پنل Vue استفاده کرده‌ام.

نصب

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

در config/sanctum.php domainهای stateful برای SPA تنظیم می‌شود.

HasApiTokens روی User

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;
}

صدور Personal Access Token

// Login API
public function login(LoginRequest $request)
{
    $user = User::where('email', $request->email)->first();

    if (! $user || ! Hash::check($request->password, $user->password)) {
        throw ValidationException::withMessages(['email' => ['Invalid credentials.']]);
    }

    $token = $user->createToken('mobile-app', ['posts:read', 'posts:write']);

    return response()->json([
        'token' => $token->plainTextToken,
        'user' => new UserResource($user),
    ]);
}

محافظت route

// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('posts', PostController::class);
    Route::post('/logout', [AuthController::class, 'logout']);
});

کلاینت header بفرستد: Authorization: Bearer {token}

logout — revoke token

$request->user()->currentAccessToken()->delete();

SPA Authentication (stateful)

اگر فرانت روی همان root domain است (مثلاً app.example.com و api.example.com)، Sanctum از cookie session هم پشتیبانی می‌کند — EnsureFrontendRequestsAreStateful middleware. جزئیات در session vs token.

Abilities (scopes)

Route::middleware(['auth:sanctum', 'abilities:posts:write'])->post('/posts', ...);

// در controller
if ($request->user()->tokenCan('posts:write')) { ... }

تفاوت Sanctum و Passport

Sanctum: first-party، ساده. Passport: OAuth2، third-party clients، سنگین‌تر.

امنیت

• HTTPS اجباری
• token را در localStorage با احتیاط — ترجیح httpOnly cookie برای SPA
• expiration در config
• rate limiting روی login

امنیت production.

جمع‌بندی

Sanctum + API Resource = backend موبایل. وب: Breeze. مجوز: Policy.

API پروژه شما