401 Unauthorized ve 403 Forbidden Farkı: API Hatası

401 Unauthorized ve 403 Forbidden farkı kısaca kimlik doğrulama ile yetkilendirme arasındaki farktır. 401, istekte geçerli kimlik doğrulama bilgilerinin bulunmadığını veya sunucu tarafından kabul edilmediğini; 403 ise sunucunun isteği ve kimliği değerlendirdikten sonra erişim izni vermediğini anlatır.

Bu nedenle 401 yalnızca “token bozuk” veya 403 yalnızca “sunucu arızası” anlamına gelmez. Hatanın hangi katmanda oluştuğunu anlamak için isteğin kimlik bilgilerini taşıyıp taşımadığına, bu bilgilerin geçerli olup olmadığına ve kullanıcının ilgili kaynağa yetkisi bulunup bulunmadığına birlikte bakmalısın.

401 Unauthorized ile 403 Forbidden arasındaki temel fark

HTTP standardındaki teknik kullanımıyla 401 Unauthorized, hedef kaynağa erişmek için geçerli kimlik doğrulama bilgilerinin eksik veya kabul edilemez olduğunu gösterir. İstek hiç kimlik bilgisi taşımıyor olabilir ya da gönderilen bilgiler yanlış, bozuk, eksik veya artık geçersiz olabilir. Günlük dilde “unauthorized” sözcüğü “yetkisiz” diye çevrilse de burada ilk soru kullanıcının role dayalı erişim izni değil, kimliğinin doğrulanıp doğrulanamadığıdır.

403 Forbidden ise sunucunun isteği anladığını ve kimlik bilgilerini değerlendirebildiğini, ancak isteği yerine getirmeyi reddettiğini ifade eder. Örneğin geçerli bir erişim belirtecine sahip kullanıcı, yalnızca yönetici rolü gerektiren bir kaynağa ulaşmaya çalışıyorsa 403 alabilir. RFC 9110, geçerli fakat erişim için yeterli olmayan kimlik bilgilerinde 403 yanıtının kullanılmasını önerir.

Basit bir kimlik doğrulamalı GET isteğinde Authorization başlığı şöyle görünebilir:

GET /profile HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

İstek 401 ile dönerse yanıt başlıklarındaki WWW-Authenticate alanını da incele. Bu alan, hedef kaynak için hangi kimlik doğrulama şemasının ve hangi parametrelerin geçerli olabileceğini belirtir; 401 üreten sunucunun en az bir kimlik doğrulama sorgulaması göndermesi HTTP standardında zorunludur.

Yine de durum kodunu tek başına kesin teşhis olarak görme. Uygulama, ters vekil sunucu veya güvenlik politikası aynı isteği farklı koşullarda 401 ya da 403 ile yanıtlayabilir. Yanıt gövdesi, başlıklar ve ilgili loglar birlikte incelendiğinde hata daha güvenilir biçimde sınıflandırılır.

Üç katmanlı teşhis: kimlik, geçerlilik ve yetki

API erişim sorunlarını çözmek için şu üç katmanlı modeli kullanabilirsin: Kimlik bilgisi var mı? Varsa kabul edilebilir durumda mı? Bu kimliğin istenen kaynağa yetkisi var mı? Bu sıralama, 401 ile 403 arasındaki ayrımı ezberlemek yerine hatanın nedenini adım adım bulmanı sağlar. Kimlik doğrulama, kimlik bilgilerinin geçerliliği ve yetkilendirme farklı kontrollerdir; tek bir “token var mı?” sorusuna indirgenmemelidir.

1. Kimlik doğrulama bilgisi var mı?

İstekte Authorization başlığı hiç yoksa veya istemci başlığı yanlış isimle gönderiyorsa ilk katman başarısız olur. Bu durumda sunucu, isteğin hangi kullanıcıya ya da istemciye ait olduğunu belirleyemez. Eksik kimlik bilgisi çoğunlukla 401 teşhisine götürür.

2. Kimlik bilgisi geçerli mi?

Başlık mevcut olsa bile token biçimi bozuk, imzası doğrulanamıyor, yanlış kimlik doğrulama şeması kullanılıyor veya token süresi dolmuş olabilir. Süresi dolan tokenın her uygulamada aynı durum koduyla eşleştirileceğini varsayma; kullanılan kimlik doğrulama politikasını, yanıt gövdesini ve logları kontrol et.

3. Doğrulanmış kimliğin yetkisi var mı?

Kimlik doğrulanmış olsa da kullanıcının belirli endpoint, kaynak veya işlem için gerekli role sahip olması gerekir. Geçerli fakat yetersiz role sahip bir token, standart yaklaşımda 403 ile ilişkilendirilir; bu aşamada yeni token göndermek yerine rol, kapsam ve kaynak politikasını incelemelisin.

Bu teşhis mantığını ve temel yazılım kavramlarını daha düzenli yapılandırmak istersen, kişiye özel birebir yazılım eğitimi programlarını inceleyebilirsin.

1. Başlık yoksa: İstemci kimlik bilgisi göndermiyor olabilir.
2. Başlık var ama reddediliyorsa: Biçim, imza, süre veya kimlik doğrulama şemasını kontrol et.
3. Kimlik geçerli olduğu hâlde erişim yoksa: Rol, kapsam ve endpoint politikasını incele.

/profile ve /admin için dört istek örneği

Aşağıdaki akış, Bearer token kullanan örnek bir REST API politikası üzerinden üç katmanı gösterir: kimliğin sunulması, token’ın geçerliliği ve kullanıcının yetkisi.

HTTP standardına göre 401, hedef kaynak için geçerli kimlik doğrulama bilgilerinin bulunmadığını gösterir ve yanıtta en az bir WWW-Authenticate challenge’ı bulunmalıdır. Geçerli kimlik bilgileri erişim için yeterli değilse 403 kullanılabilir; Bearer token akışında süresi dolmuş veya bozuk token için invalid_token, yetersiz kapsam için insufficient_scope örneklenir.

Bu tablo belirli bir uygulama politikasındaki örnek akıştır. Endpoint’in güvenlik katmanı, kullanılan kimlik doğrulama şeması ve kaynak sahipliği kuralları değiştikçe farklı yanıt gövdeleri veya durum kodları görülebilir. Bu nedenle 401’i yalnızca “token hatası”, 403’ü de “sunucu arızası” olarak ezberlemek yerine hangi katmanın başarısız olduğunu teşhis et.

API hatasını şu sırayla kontrol edin

Örneğin, istemcinin admin yetkisi olmayan geçerli bir token gönderdiği durumda yanıt şöyle görünebilir:

GET /admin HTTP/1.1
Host: api.example.test
Authorization: Bearer <token>

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error":"insufficient_scope","request_id":"abc123"}

1. Yanıt gövdesi: error, açıklama, correlation_id veya request_id alanlarını ara. Beklenen çıktı, sorunun invalid_token mı yoksa insufficient_scope mu olduğunu anlamaktır.
2. Yanıt ve istek başlıkları: HTTP durumunu, WWW-Authenticate ve Content-Type başlıklarını; ayrıca istemcinin gerçekten gönderdiği Authorization başlığını kontrol et. 401 yanıtında WWW-Authenticate bulunması beklenir.
3. Token: Token’ın varlığını, şemasını, biçimini, kullanılan token türünde imza gerekiyorsa imzasını ve süresini kontrol et. Sunucunun Bearer gibi hangi kimlik doğrulama şemasını beklediğini de doğrula. Bearer akışında geçersiz veya süresi dolmuş token genellikle 401 teşhisine götürür.
4. Rol veya izin: Endpoint’in istediği rol ya da scope ile token’daki veya tokenla ilişkili sunucu kaydındaki izinleri karşılaştır. Kimlik geçerli olduğu hâlde izin yetersizse aynı token’ı tekrar göndermek çözüm değildir; örnek politika 403 döndürür.
5. Endpoint ve HTTP metodu: Yolun, metodun, ortam adresinin ve erişilen kaynağın kullanıcıya ait olup olmadığını kontrol et. Böylece sorunun kimlik katmanında mı, yanlış route veya kaynak sahipliği kuralında mı olduğu netleşir.

Bu sıralamayı kendi hızında tekrar etmek ve HTTP temellerini pekiştirmek için Berk Akademi’nin video eğitimleri ek kaynak olarak kullanılabilir.

İstemci, proxy ve sunucu loglarını nasıl okuyabilirsiniz?

Aynı istek, istemcide ve uygulama sunucusunda farklı görünebilir. Ayrıca gördüğün 401 veya 403, uygulamadan değil, HTTP trafiğini işleyen ters proxy’den ya da API ağ geçidinden geliyor olabilir. Önce yanıtı hangi katmanın ürettiğini belirle.

1. Zaman damgasını ve istek kimliğini eşleştir. Katmanlar arasında taşınan istek kimliğini (request ID) takip et. Saat dilimi ve cihaz saati farklarını dikkate al; yalnızca zamanların yakın olması yeterli değildir.
2. HTTP metodunu ve endpoint’i doğrula. GET /profile ile POST /profile kayıtlarını karıştırma. Proxy adres yolunu yeniden yazıyorsa istemcideki yolu uygulamadaki karşılığıyla, yönlendirme ayarları üzerinden eşleştir.
3. Başlıkları güvenli biçimde incele. Authorization başlığının varlığını ve doğrulama şemasını kontrol et. Token’ı düz metin loglama; kaydedilmeden önce Authorization: Bearer [MASKELENDİ] biçiminde maskele.
4. Proxy girişini ve çıkışını karşılaştır. Başlık girişte var, uygulamada yoksa başlığı değiştiren, boşaltan veya aktarmayan yapılandırmaları incele. Token yenilemeden önce bilginin hangi noktada kaybolduğunu araştır.
5. Sunucunun doğrulama ve yetkilendirme kararlarını ayır. Token kabul edilmemiş mi, yoksa doğrulanmış kullanıcı erişim kuralında mı engellenmiş? Loglarda bu iki sonucu ayrı alanlarda izle.

İstemcinin aldığı yanıt başlıklarını ve gövdesini, proxy loguyla ve uygulamanın yanıt kaydıyla birlikte karşılaştır. Uygulama logunda kayıt göremediğinde hemen “istek ulaşmadı” sonucuna varma; önce loglamanın etkin ve doğru çalıştığını kontrol et.

Alan adları yalnızca gösterim amaçlı olan şu üç temsili kayıt, teşhis katmanını somutlaştırır:

• Başlık hiç gitmemiş: İstemcide authorization_present=false görülüyor. Önce kimlik bilgisini isteğe ekleyen adımı incele.
• Token sunucuda reddedilmiş: Uygulamada token_valid=false, reason=revoked görülüyor. Token ulaşmış, ancak iptal edildiği için kabul edilmemiş.
• Rol yetersiz: token_valid=true, role=user, required_role=admin, decision=deny görülüyor. Kimlik geçerli; yönetici rolü isteyen /admin için yetki yetersiz.

401 ve 403 hakkında sık yapılan yanlış çıkarımlar

Her 401, token’ın süresinin dolduğunu göstermez. Eksik kimlik bilgisini, hatalı biçimli veya iptal edilmiş token’ı ve kabul edilmeyen doğrulama yöntemini de incele. “Unauthorized” günlük dilde “yetkisiz” çağrışımı yapsa da 401’in teknik odağı, hedef kaynak için geçerli kimlik doğrulama bilgisinin bulunmamasıdır.

403, tek başına sunucu arızası değildir. Geçerli kimlik; yetersiz rol, kaynak sahipliği, endpoint politikası veya başka bir erişim kuralı nedeniyle engellenebilir. Üstelik 403, kimliğin mutlaka doğrulandığını da kanıtlamaz; ret nedeni kimlik bilgilerinden bağımsız olabilir.

Kimlik bilgisi sorunu her sistemde mutlaka 401 döndürmez. Örneğin hatalı kurulmuş bir Bearer doğrulama isteği 400 yanıtı alabilir; API ağ geçitleri de farklı hata eşlemeleri kullanabilir. HTTP durum kodunu, yanıtın hata ayrıntısını ve sistem dokümantasyonunu birlikte değerlendir.

Programlama bilgini ve algoritmik düşünme temelini değerlendirmek için Berk Akademi yazılım bilgi testlerinden yararlanabilirsin. Bu testleri API hatasını doğrudan çözen araçlar olarak değil, temel bilgilerini gözden geçirme fırsatı olarak kullan.

Sık Sorulan Sorular

401 Unauthorized ile 403 Forbidden arasındaki fark tek cümlede nasıl açıklanır?

401, hedef kaynak için geçerli kimlik doğrulama bilgisinin bulunmadığını; 403, sunucunun isteği anladığı hâlde yerine getirmeyi reddettiğini belirtir.

401 yanıtı alıyorsam token kesinlikle süresi dolmuş mudur?

Hayır. Token gönderilmemiş, iptal edilmiş, bozulmuş veya başka nedenle geçersiz olabilir; 401 tek başına sürenin dolduğunu kanıtlamaz.

403 yanıtı neden geçerli bir kullanıcı token’ıyla alınabilir?

Kimliğin doğrulanması her kaynağa erişim sağlamaz. Kullanıcının rolü, token’ın izin kapsamı veya kaynak sahipliği, istenen işlem için yeterli olmayabilir.

WWW-Authenticate başlığı 401 yanıtında ne işe yarar?

Hedef kaynak için kullanılabilecek kimlik doğrulama şemasını ve parametrelerini bildirir. RFC 9110’a göre 401 üreten sunucu, en az bir kimlik doğrulama çağrısı içeren bu başlığı göndermek zorundadır. Örnek: WWW-Authenticate: Bearer realm="api".

Bir 401 veya 403 yanıtının proxy’den mi yoksa API sunucusundan mı geldiği nasıl anlaşılır?

Yanıt başlıklarını ve gövdesini, aynı istek kimliğine ait proxy ve uygulama loglarıyla eşleştir. Proxy’deki ret kararını ve uygulamadaki yanıt kaydını karşılaştır; yalnızca durum koduna bakma.

Bir sonraki hatada önce isteğin izini sür; kimlik doğrulama, kimlik bilgilerinin geçerliliği ve yetkilendirme adımlarını ayırarak logların işaret ettiği noktayı düzelt.