Laravel Sanctum ile API Authentication Rehberi

Laravel Sanctum, modern bir API'ye kimlik doğrulama eklemenin en sade yoludur. JWT kütüphanelerinin karmaşıklığına ya da OAuth'un ağır kurulumuna girmeden iki ihtiyacı tek pakette çözer: mobil uygulamalar ve üçüncü taraf istemciler için API token'ları, ve aynı domaindeki React/Vue gibi SPA'lar için çerez tabanlı oturumlar. Bu yazıda her iki yöntemi de gerçek kodla, çalışan örneklerle kuruyoruz.

Sanctum ne zaman, neden?

Laravel ekosisteminde kimlik doğrulama için üç ana seçenek vardır: tam yetkili bir OAuth2 sunucusu isteyen projeler için Passport, durağan (stateless) JWT için harici kütüphaneler, ve çoğu uygulamanın gerçekten ihtiyaç duyduğu hafif çözüm olan Sanctum. Şu durumların birindeyseniz Sanctum doğru tercihtir:

Mobil uygulamanız veya CLI aracınız var ve her isteğe basit bir Bearer token'ı eklemek istiyorsunuz.
Frontend'iniz (SPA) Laravel API'siyle aynı üst domainde çalışıyor ve gerçek bir OAuth akışına ihtiyacınız yok.
Token'lara yetenek (ability) tabanlı izinler vermek istiyorsunuz; örneğin bir token yalnızca okuma yapabilsin.

OAuth2 akışlarına (authorization code, client credentials) ihtiyaç duyan, harici geliştiricilere açık bir platform kuruyorsanız Passport daha uygundur. Çoğu pratik senaryoda ise Sanctum hem daha hızlı kurulur hem de daha az bakım gerektirir.

Kurulum

Laravel 11 ve 12'de Sanctum, install:api komutuyla tek adımda gelir. Bu komut paketi yayınlar, migration'ı ekler ve API route dosyasını hazırlar:

php artisan install:api

Komut çalıştıktan sonra migration'lar zaten çalıştırılmış olur ve personal_access_tokens tablosu oluşur. Kullanıcı modelinize HasApiTokens trait'ini eklemeniz yeterlidir:

use Laravel\Sanctum\HasApiTokens;

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

Bu trait, modele createToken() metodunu ve tokens() ilişkisini kazandırır. Artık token üretebiliriz.

API token'ları üretmek ve kullanmak

En yaygın senaryo: kullanıcı e-posta ve şifresiyle giriş yapar, siz de ona bir token döndürürsünüz. İstemci bu token'ı saklar ve sonraki isteklerde Authorization: Bearer <token> başlığıyla gönderir. Basit bir login controller'ı şöyle görünür:

use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Illuminate\Support\Facades\Hash;
use App\Models\User;

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' => ['Kimlik bilgileri hatalı.'],
        ]);
    }

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

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

Burada önemli bir nokta var: plainTextToken token'ın açık halini yalnızca üretildiği anda döndürür. Veritabanında token'ın yalnızca hash'i saklanır, dolayısıyla bu değeri kaybederseniz geri alamazsınız — istemcinin onu hemen kaydetmesi gerekir.

Korumalı route'ları auth:sanctum middleware'iyle kapatın. routes/api.php içinde:

use Illuminate\Support\Facades\Route;

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

İstemci tarafında istek şuna benzer:

curl https://api.ornek.com/api/user \
  -H "Authorization: Bearer 1|abcDEF..." \
  -H "Accept: application/json"

Token yetenekleri (abilities)

Sanctum, her token'a belirli yetenekler atamanıza izin verir. Bu, bir token'ın yapabileceklerini sınırlamanın temiz bir yoludur:

$token = $user->createToken('rapor-botu', ['post:read'])->plainTextToken;

Controller veya route içinde bu yeteneği kontrol edebilirsiniz:

if ($request->user()->tokenCan('post:read')) {
    // okuma izni var
}

Ayrıca route'lara abilities ve ability middleware'lerini ekleyerek erişimi kapı seviyesinde kısıtlayabilirsiniz. Yeteneklerin yalnızca bir kolaylık katmanı olduğunu unutmayın; gerçek yetkilendirme mantığını yine de uygulamanızda doğrulamanız gerekir.

SPA kimlik doğrulaması

Aynı üst domainde çalışan bir SPA için Sanctum, token yerine Laravel'in oturum çerezlerini kullanır. Bu yaklaşım daha güvenlidir çünkü token'ı JavaScript'in eriştiği localStorage'da tutmanıza gerek kalmaz; tarayıcı HttpOnly çerezi otomatik yönetir. Akış şöyledir:

SPA önce /sanctum/csrf-cookie uç noktasından bir CSRF çerezi ister.
Ardından /login route'una normal bir web isteği gönderir; başarılı olursa oturum çerezi set edilir.
Sonraki tüm API istekleri bu çerezle, otomatik olarak kimliklenmiş gelir.

Bunun çalışması için üç ayar önemlidir. Önce config/cors.php dosyasında supports_credentials değerini true yapın. İkincisi, .env dosyasında SPA'nızın domainini tanıtın:

SANCTUM_STATEFUL_DOMAINS=localhost:3000
SESSION_DOMAIN=localhost

Üçüncüsü, istemcide isteklerin çerez göndermesi gerekir. Axios kullanıyorsanız:

import axios from 'axios';

axios.defaults.withCredentials = true;
axios.defaults.withXSRFToken = true;

await axios.get('/sanctum/csrf-cookie');
await axios.post('/login', { email, password });
const { data } = await axios.get('/api/user');

Burada en sık yapılan hata, SPA ile API'yi tamamen farklı domainlerde çalıştırıp neden oturumun tutmadığını anlamamaktır. Çerez tabanlı yöntem, ikisinin aynı üst domaini paylaşmasını (örneğin app.ornek.com ve api.ornek.com) gerektirir.

Token'ları iptal etmek ve güvenlik

Kullanıcı çıkış yaptığında ya da bir cihazı kaybettiğinde token'ları geçersiz kılmak gerekir. Mevcut token'ı silmek için:

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

Tüm token'ları iptal etmek (tüm cihazlardan çıkış) için:

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

Birkaç güvenlik notu: token'lara config/sanctum.php üzerinden son kullanma süresi (expiration) tanımlayın, API'nizi her zaman HTTPS arkasında çalıştırın, ve login uç noktanıza throttle middleware'i ekleyerek kaba kuvvet denemelerini sınırlayın. SPA tarafında ise CSRF korumasının devrede olması, çerez tabanlı yöntemin getirdiği en büyük avantajdır.

Sık Sorulan Sorular

Sanctum mı Passport mı kullanmalıyım?

Harici geliştiricilere açık tam bir OAuth2 sunucusu kurmuyorsanız Sanctum'u tercih edin. Mobil uygulama token'ları ve birinci taraf SPA oturumları için Sanctum hem daha hafiftir hem de bakımı kolaydır. Passport, authorization code gibi OAuth akışlarına ihtiyaç olduğunda anlamlıdır.

Token'ları nerede saklamalıyım?

Mobil uygulamalarda token'ı platformun güvenli depolama alanında (iOS Keychain, Android Keystore) tutun. SPA'larda ise token tabanlı yöntem yerine çerez tabanlı SPA kimlik doğrulamasını kullanın; böylece token'ı JavaScript'in eriştiği localStorage'da tutmak zorunda kalmazsınız.

SPA login'i neden 419 hatası veriyor?

419 hatası genellikle CSRF token uyuşmazlığıdır. İsteklerden önce /sanctum/csrf-cookie çağırdığınızdan, istemcinin çerez gönderdiğinden (withCredentials), ve SANCTUM_STATEFUL_DOMAINS ile SESSION_DOMAIN değerlerinin doğru ayarlandığından emin olun.

API'nize güvenli bir kimlik doğrulama katmanı mı kurmak istiyorsunuz? Laravel Sanctum entegrasyonu, SPA oturumları ya da mobil API'leriniz için yardıma ihtiyacınız olursa benimle iletişime geçin — projenize en uygun çözümü birlikte kuralım.