Projeman
Ana Sayfa Blog Projeler İletişim
· Admin

Laravel Passport vs Sanctum: Hangisini Kullanmalısın?

Laravel

API authentication konusu Laravel ekosisteminde en sık sorulan sorulardan biri. , iki farklı paket var, ikisi de resmi, ikisi de iyi -- ama hangisi senin projen icin dogru? Bu yazıda Passport ve Sanctum'u detaylıca karşılaştırıyorum, kurulum örnekleriyle birlikte.

Kisa Cevap

Projelerin yuzde 90'inda Sanctum yeterli. Passport'a ihtiyacin olan tek senaryo: ucuncu parti uygulamalara OAuth2 ile erisim veriyorsan. Yani kendi API'ni baskalarinin kullanmasini istiyorsan.

Eger SPA (Single Page Application), mobil uygulama veya first-party API yapiyorsan -- Sanctum kullan, hayatini kolaylastir.

Sanctum Nedir?

Sanctum, Laravel'in hafif API authentication paketi. Iki farkli authentication mekanizmasi sunuyor:

  1. SPA Authentication: Cookie-based session authentication. Ayri bir token olusturmaya gerek yok.
  2. API Token Authentication: Her kullaniciya benzersiz token verilir. Mobil uygulamalar icin ideal.

Sanctum Kurulumu

Laravel 11+ ile Sanctum zaten yuklü geliyor. Ama sifirdan kurmak istersen:

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

User modeline trait'i ekle:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

Sanctum ile Token Olusturma

// LoginController.php
public function login(Request $request)
{
    $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    $user = User::where('email', $request->email)->first();

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

    // Token olustur
    $token = $user->createToken('mobile-app')->plainTextToken;

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

Sanctum ile Route Koruma

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

    Route::apiResource('posts', PostController::class);
});

Token Yetenekleri (Abilities)

Sanctum'da token'lara yetenek atayabilirsin:

// Sadece okuma yetkisi olan token
$token = $user->createToken('read-only', ['posts:read']);

// Tam yetkili token
$token = $user->createToken('admin', ['*']);

Controller'da kontrol:

public function update(Request $request, Post $post)
{
    if (! $request->user()->tokenCan('posts:update')) {
        abort(403, 'Bu token guncelleme yetkisine sahip degil.');
    }

    // ...
}

SPA Authentication (Cookie-Based)

SPA icin Sanctum'un en guzel tarafi: ayri token yonetimi yok. Laravel'in standart session authentication'ini kullaniyor.

config/sanctum.php dosyasinda stateful domain'leri tanimla:

'stateful' => explode(',', env(
    'SANCTUM_STATEFUL_DOMAINS',
    'localhost,localhost:3000,localhost:5173,127.0.0.1'
)),

Frontend'den once CSRF token al:

// axios ile
await axios.get('/sanctum/csrf-cookie');

// Sonra normal login
await axios.post('/login', {
    email: '[email protected]',
    password: 'password',
});

// Artik cookie-based auth ile API'ye erisebilirsin
const response = await axios.get('/api/user');

Passport Nedir?

Passport, Laravel icin tam OAuth2 server implementasyonu. Eger "Google ile giris yap" gibi bir OAuth provider olacaksan veya ucuncu parti gelistiricilere API erisimi vereceksen Passport gerekli.

Passport Kurulumu

composer require laravel/passport
php artisan migrate
php artisan passport:install

User modeline trait ekle:

use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

config/auth.php dosyasinda guard'i ayarla:

'guards' => [
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

Passport ile Client Olusturma

# Personal Access Client
php artisan passport:client --personal

# Password Grant Client
php artisan passport:client --password

# Authorization Code Client (ucuncu parti icin)
php artisan passport:client

Passport ile Token Alma (Password Grant)

// Token almak icin HTTP istegi
$response = Http::asForm()->post('https://your-app.com/oauth/token', [
    'grant_type' => 'password',
    'client_id' => env('PASSPORT_CLIENT_ID'),
    'client_secret' => env('PASSPORT_CLIENT_SECRET'),
    'username' => '[email protected]',
    'password' => 'secret',
    'scope' => '*',
]);

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

Passport Scope Tanimlama

// AuthServiceProvider.php
use Laravel\Passport\Passport;

public function boot()
{
    Passport::tokensCan([
        'posts-read' => 'Yazilari okuma',
        'posts-write' => 'Yazi olusturma ve guncelleme',
        'users-read' => 'Kullanici bilgilerini okuma',
    ]);
}

Route'larda scope kontrolu:

Route::middleware(['auth:api', 'scope:posts-read'])->group(function () {
    Route::get('/posts', [PostController::class, 'index']);
});

Route::middleware(['auth:api', 'scopes:posts-read,posts-write'])->group(function () {
    Route::post('/posts', [PostController::class, 'store']);
});

Karsilastirma Tablosu

Ozellik Sanctum Passport
Kurulum Zorlugu Kolay Orta-Zor
OAuth2 Destegi Yok Tam
SPA Authentication Cookie-based (ideal) Mumkun ama overkill
Mobil Token Var Var
Token Yenileme (Refresh) Manuel Otomatik (refresh token)
Ucuncu Parti Erisim Yok Tam OAuth2 flow
Token Scope/Ability Basit abilities Tam OAuth2 scopes
Veritabani Tablolari 1 (personal_access_tokens) 5+ tablo
Token Suresi Opsiyonel Ayarlanabilir
Performans Hafif Daha agir
Dokumantasyon Basit Kapsamli ama karisik

Passport'tan Sanctum'a Gecis Rehberi

Eger Passport kullaniyorsan ve Sanctum'a gecmek istiyorsan, adim adim:

1. Sanctum'u Yukle

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

2. User Model'i Guncelle

// Eskisi (Passport)
use Laravel\Passport\HasApiTokens;

// Yenisi (Sanctum)
use Laravel\Sanctum\HasApiTokens;

3. Auth Guard'i Guncelle

// config/auth.php
'guards' => [
    'api' => [
        'driver' => 'sanctum', // 'passport' yerine
    ],
],

4. Route Middleware'i Guncelle

// Eskisi
Route::middleware('auth:api')->group(function () { ... });

// Yenisi
Route::middleware('auth:sanctum')->group(function () { ... });

5. Token Olusturma Kodlarini Guncelle

// Eskisi (Passport)
$token = $user->createToken('MyApp')->accessToken;

// Yenisi (Sanctum)
$token = $user->createToken('MyApp')->plainTextToken;

6. Scope'lari Ability'lere Cevir

// Eskisi (Passport scope)
$token = $user->createToken('MyApp', ['posts-read']);
$user->tokenCan('posts-read'); // Ayni syntax!

// Sanctum'da da ayni sekilde calisiyor
$token = $user->createToken('MyApp', ['posts-read']);
$user->tokenCan('posts-read');

7. Passport'u Kaldir

composer remove laravel/passport

# Passport tablolarini kaldirmak icin migration yaz
php artisan make:migration drop_passport_tables

public function up()
{
    Schema::dropIfExists('oauth_access_tokens');
    Schema::dropIfExists('oauth_auth_codes');
    Schema::dropIfExists('oauth_clients');
    Schema::dropIfExists('oauth_personal_access_clients');
    Schema::dropIfExists('oauth_refresh_tokens');
}

Sik Yapilan Hatalar

1. SPA'da Token Kullanmak

Cookie-based auth varken neden token yoneteceksin ki? SPA icin Sanctum'un session authentication'ini kullan.

// YANLIS: SPA'da token saklama
localStorage.setItem('token', response.data.token);
axios.defaults.headers.common['Authorization'] = `Bearer ${token}`;

// DOGRU: Cookie-based auth
await axios.get('/sanctum/csrf-cookie');
await axios.post('/login', credentials);
// Artik cookie otomatik gonderiliyor

2. Sanctum'da CORS Ayarini Unutmak

// config/cors.php
'paths' => ['api/*', 'sanctum/csrf-cookie'],
'supports_credentials' => true, // BU COK ONEMLI!

Frontend'de de credentials gonder:

axios.defaults.withCredentials = true;

3. Token Sureleri Ayarlamamak

// config/sanctum.php
'expiration' => 60 * 24, // 24 saat (dakika cinsinden)

Suresi dolmus token'lari temizle:

php artisan sanctum:prune-expired --hours=24

Bunu schedule'a ekle:

// routes/console.php veya app/Console/Kernel.php
Schedule::command('sanctum:prune-expired --hours=24')->daily();

4. Passport'u Gereksiz Yere Secmek

Bircok gelistirici "daha profesyonel gorunuyor" diye Passport seciyor. Ama Passport'un getirdigi karmasiklik cogu projede gereksiz. Sanctum ile 5 dakikada yapacagin isi Passport ile 30 dakikada yapiyorsun.

Ne Zaman Passport?

Passport'a gercekten ihtiyacin olan senaryolar:

  • OAuth2 Provider olacaksin (GitHub, Google gibi)
  • Ucuncu parti gelistiriciler API'ni kullanacak
  • Authorization Code Grant gerekiyor
  • Client Credentials Grant (machine-to-machine) gerekiyor
  • Refresh token mekanizmasi zorunlu

Ne Zaman Sanctum?

  • SPA + Laravel API
  • Mobil uygulama + Laravel API
  • First-party API (kendi frontend'in kendi backend'ini kullaniyor)
  • Basit token-based authentication
  • Microservice'ler arasi iletisim (basit)

Sonuc

Sanctum, Laravel ekosisteminde API authentication icin varsayilan secim olmali. Hafif, anlasilir ve cogu kullanim senaryosu icin yeterli. Passport ise OAuth2 ihtiyaci olan projeler icin orada duruyor -- ama o ihtiyacin olup olmadigini iyi degerlendir.

Tecrubelerime dayanarak soyleyebilirim: Passport kullandigim projelerin cogu aslinda Sanctum ile de cozulebilirdi. Fazladan karmasiklik, fazladan tablo, fazladan konfigurasyon... hepsi gereksizdi. Basit bas, gerekirse buyut.

#Laravel #API #Security

İlgili Yazılar

Laravel 12 ile Gelen Yenilikler

23 Feb 2026

Docker ile Laravel Development Ortamı

14 Feb 2026

REST API Best Practices: Laravel ile

08 Feb 2026