Yazılım

Laravel Sanctum kurulumu: Gerçekten çalışan ve çoğu kişinin zorlandığı noktalar

Son güncelleme: 8 Mart 2026 14:55

teknomers

Paylaş

Paylaş

Sanctum’u şu ana kadar 8 veya 9 Laravel projesinde kurdum — bordro sistemleri, SaaS araçları, e-ticaret API’leri. Genellikle bir junior geliştiriciyi işe alırken veya herhangi birinin kodunu gözden geçirirken, aynı 3-4 hatayı tekrar tekrar görüyorum. İşte bu hataları önleyecek bir kurulum ve sorunları çözmenin yolları.

<hr/>

<h2>
  <a name="first-what-sanctum-actually-does" href="#first-what-sanctum-actually-does"></a>
  İlk olarak: Sanctum ne yapar?
</h2>

<p>Sanctum, düz metin bir token üretir, bunu <code>personal_access_tokens</code> tablosunda hashlenmiş haliyle saklar ve her istekte veritabanında doğrulama yapar. Bu kadar basit. JWT, imza yok, çözümleme yok — sadece bir veritabanı kaydı.</p>

<p>Bu durum, token iptali Sanctum ile oldukça kolay, JWT ile ise karmaşık hale gelir. Satırı silin, token anında geçersiz olur.</p>

<hr/>

<h2>
  <a name="the-setup-laravel-12" href="#the-setup-laravel-12"></a>
  Kurulum (Laravel 12)
</h2>

<p><strong>Adım 1 — Kurulum (Sadece Laravel 10 ve altı için)</strong></p>

<p>Laravel 11 ve 12, Sanctum ile birlikte gelir. Eğer 10 kullanıyorsanız:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight shell"><code>composer require laravel/sanctum

php artisan vendor:publish –provider=”Laravel\Sanctum\SanctumServiceProvider”
php artisan migrate

<p><strong>Adım 2 — User modelinize trait ekleyin</strong></p>

<p>Genellikle çoğu kişinin unuttuğu bir adım:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
use HasApiTokens;
}

<p>Bu eklenmezse, <code>createToken()</code> yöntemi modelinizde mevcut olmaz ve karmaşık bir hata alırsınız.</p>

<p><strong>Adım 3 — Route'lar</strong><br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>Route::prefix('v1')->group(function () {
// Public
Route::post('auth/register', [AuthController::class, 'register']);
Route::post('auth/login', [AuthController::class, 'login']);

// Protected
Route::middleware('auth:sanctum')->group(function () {
    Route::post('auth/logout', [AuthController::class, 'logout']);
    Route::get('auth/me', [AuthController::class, 'me']);
});

});

<p><strong>Adım 4 — AuthController</strong><br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>public function login(Request $request)

{
$request->validate([
’email’ => ‘required|email’,
‘password’ => ‘required’,
]);

if (!Auth::attempt($request->only('email', 'password'))) {
    return response()->json(['message' => 'Invalid credentials'], 401);
}

$token = Auth::user()->createToken('auth_token')->plainTextToken;

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

}

public function logout(Request $request)
{
$request->user()->currentAccessToken()->delete();
return response()->json([‘message’ => ‘Logged out’]);
}

<p><strong>Adım 5 — Token'i gönderin</strong><br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>Authorization: Bearer 1|yourtokenhere...

<p>Formatı not edin — <code>1|randomstring</code>. İlk sayı, veritabanındaki token kimliğidir. Tam dizeyi gönderin.</p>

<hr/>

<h2>
  <a name="the-4-things-that-will-silently-break-your-setup" href="#the-4-things-that-will-silently-break-your-setup"></a>
  Kurulumunuzu sessizce bozacak 4 şey
</h2>

<p><strong>1. User modelinde <code>HasApiTokens</code> unutmamak</strong><br/> 
  Her zaman önce bunu kontrol edin; <code>createToken()</code> hata verebilir. 
</p>

<p><strong>2. Token'i yanlış göndermek</strong><br/> 
  <code>Authorization: Bearer YOUR_TOKEN</code> olarak gönderilmelidir. Sorgu parametresi, çerez veya <code>Token YOUR_TOKEN</code> değil. Tam olarak Bearer olmalıdır.
</p>

<p><strong>3. Migrations'ı çalıştırmamak</strong><br/> 
  <code>personal_access_tokens</code> tablosu henüz yok. <code>php artisan migrate</code> komutunu çalıştırın ve tablonun olduğundan emin olun.
</p>

<p><strong>4. CORS'un frontend'inizi engellemesi</strong><br/> 
  <code>config/cors.php</code> dosyasına frontend URL'nizi ekleyin:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>'allowed_origins' => ['https://yourfrontend.com'],

‘supports_credentials’ => true,

<hr/>

<h2>
  <a name="revoking-tokens" href="#revoking-tokens"></a>
  Token'ları iptal etme
</h2>

<p>Sanctum’un JWT’ye göre parladığı yer:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>// Mevcut cihaza oturumu kapatma

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

// Tüm cihazlardan oturumu kapatma
$user->tokens()->delete();

<p>JWT kullanıyorsanız, bir yasaklama listesine ve ek altyapıya ihtiyacınız olur. Ancak Sanctum ile bu tek bir satırla çözülür.</p>

<hr/>

<h2>
  <a name="setting-token-expiry" href="#setting-token-expiry"></a>
  Token süresini ayarlama
</h2>

<p><code>config/sanctum.php</code> içinde:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code>// 60 gün sonra sona erer (değer dakikadır)

‘expiration’ => 60 24 60,

// Asla sona ermez
‘expiration’ => null,

<hr/>

<h2>
  <a name="should-you-use-sanctum-or-jwt" href="#should-you-use-sanctum-or-jwt"></a>
  Sanctum mu yoksa JWT mi kullanmalısınız?
</h2>

<p><strong>Sanctum</strong> kullanın eğer kendi uygulamanız için (SPA, mobil) bir API geliştiriyorsanız. <strong>JWT</strong> ise sadece stateless servisler arası kimlik doğrulama gerekiyorsa kullanılmalıdır. Laravel projelerinin %90'ı için Sanctum doğru tercihtir.</p>

<p>Burada daha ayrıntılı bir açıklama yazdım: <a href="https://pola5h.github.io/blog/laravel-api-authentication-jwt-sanctum/" target="_blank" rel="noopener noreferrer">Laravel Sanctum JWT kullanıyor mu? →</a></p>

<hr/>

<h2>
  <a name="full-tutorial" href="#full-tutorial"></a>
  Tam eğitim
</h2>

<p>Kayıt, kendim endpoint'i, token yetkileri ve daha fazlasıyla birlikte komple versiyonu istiyorsanız, burada yazdım:</p>

<p>👉 <a href="https://pola5h.github.io/blog/laravel-sanctum-tutorial/" target="_blank" rel="noopener noreferrer">Laravel Sanctum Kurulum Eğitimi (2026)</a></p>

<hr/>

<h2>
  <a name="already-using-sanctum" href="#already-using-sanctum"></a>
  Zaten Sanctum kullanıyor musunuz?
</h2>

<p>Önceden yapılandırılmış bir <a href="https://pola5h.github.io/laravel-api-starter-kit/" target="_blank" rel="noopener noreferrer">Laravel API Başlangıç Kiti</a> oluşturdum — kimlik doğrulama, roller, sayfalama, API versiyonlama her şey dahil. Her yeni projede birkaç saat kazandırır. Kontrol etmek isterseniz, Gumroad'da $19.</p>

<hr/>

<p>Sanctum ile hangi sorunlarla karşılaştınız? Aşağıda belirtin — hata ayıklamak konusunda yardımcı olmaktan memnuniyet duyarım.</p>