401 Hatası Nedir? Unauthorized Ne Demek, Nasıl Çözülür

401 Unauthorized Hatası Nedir?

401 Unauthorized hatası, sunucunun kim olduğunuzu kanıtlamanızı istediği, ancak isteğinizin bunu yapmadığı ya da gönderdiği kimlik bilgilerinin reddedildiği anlamına gelir. Parola yok, yanlış parola, süresi dolmuş token veya eksik API anahtarı: hepsi aynı sonuca varır.

HTTP standardı bunu, “hedef kaynak için geçerli kimlik doğrulama bilgilerinden yoksun” bir istek olarak tanımlar ve 401 gönderen bir sunucu, kabul ettiği giriş yöntemini belirten bir WWW-Authenticate başlığı İÇERMELİDİR (RFC 9110 §15.5.2).

Kısacası sunucu, sizi içeri almadan önce “Kimsiniz?” diye soruyor.

401 Hatası Nasıl Görünür

Göreceğiniz sayfa sunucuya ve uygulamaya göre değişir:

• 401 Unauthorized — standart durum satırı ve çoğu uygulamanın kullandığı ifade
• 401 Authorization Required — nginx'in yerleşik 401 sayfasının başlığı; altında “nginx” yazar (genellikle sürümüyle) (nginx kaynak kodu); eski Apache 2.2 sunucuları da aynı sözcükleri kullanır
• Unauthorized · This server could not verify that you are authorized to access the document requested — Apache'nin varsayılan sayfası
• 401 - Unauthorized: Access is denied due to invalid credentials — IIS; ayrıntılı sayfa (yalnızca sunucunun kendisinde görünür) ve IIS günlüğü nedeni 401.1, 401.2 veya 401.3 olarak bildirir: oturum açma başarısız, sunucu yapılandırması veya dosya izinleri
• Tarayıcıda bir giriş kutusu — sunucu HTTP Basic veya Digest kimlik doğrulaması istediğinde, IIS'te ve şirket intranetlerinde ise NTLM veya Negotiate istediğinde
• Bu sayfa çalışmıyor · HTTP ERROR 401 — 401 yanıtının kendi sayfası olmadığında Chrome'un gösterdiği sayfa
• Bir API'den gelen JSON, örneğin {"error":{"message":"Missing Authentication header","code":401}}

Tarayıcılar giriş kutusunu yalnızca bu giriş yöntemleri için gösterir. Token tabanlı API'ler (“Bearer”) onu hiç tetiklemez; bunların 401 yanıtı, uygulamanın işlediği JSON olarak gelir. Giriş formu olan siteler, oturumu kapalı ziyaretçiyi genellikle 401 yerine 302 yönlendirmesiyle giriş sayfasına gönderir.

nginx'te “401 Authorization Required”

Bu başlık, nginx'in yerleşik 401 sayfasından gelir. Bir location auth_basic ile korunuyorsa ve istek kullanıcı adı ile parola içermiyorsa ya da yanlış olanları içeriyorsa bu sayfayı görürsünüz; tarayıcının giriş kutusunu iptal etmek de aynı sayfayı gösterir.

Ziyaretçiyseniz sayfayı yenileyin ve site sahibinin verdiği kullanıcı adı ile parolayı girin. Bunlar sitedeki hesaplardan ayrıdır: Basic kimlik doğrulaması, sunucudaki bir parola dosyasını kontrol eder.

Site sahibiyseniz koruma böyle kurulur ve bir yol herkese açık böyle bırakılır:

# Create the password file (htpasswd comes with apache2-utils or httpd-tools)
#   sudo htpasswd -c /etc/nginx/.htpasswd alice   # -c creates the file: leave it out when adding users

location /admin/ {
    auth_basic           "Admin area";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

# Inside a protected server block, open one path to everyone
location /public/ {
    auth_basic off;
}

# Test, then reload
#   curl -I -u alice:PASSWORD https://example.com/admin/
#   sudo nginx -t && sudo systemctl reload nginx

Doğru parolayla hâlâ 401 mi alıyorsunuz? Kullanıcının dosyada olduğunu kontrol edin (htpasswd -c dosyanın üzerine yazar ve önceki kullanıcıları siler) ve nginx'in arkasındaki uygulamanın da Authorization başlığına ihtiyaç duyup duymadığına bakın: nginx'in Basic girişi ile uygulamanın Bearer tokenleri aynı başlığı kullanır, bu yüzden uygulama nginx'in kimlik bilgilerini alır ve reddeder.

401 ile 403 Arasındaki Fark Nedir?

401 ve 403 kodları sık karıştırılır. Kısaca: 401 “Kim olduğunuzu bilmiyorum”, 403 ise “Sizi içeri almıyorum” demektir; sorun kimliğinizde olsun ya da olmasın.

Pratik bir kural: doğru kullanıcı adı ve parola (veya API anahtarı) vermek sorunu çözecekse sunucu 401 döndürmelidir. Kullanıcı zaten kimlik doğrulaması yapmış ama o kaynağa erişimi yoksa sunucu 403 Forbidden döndürmelidir.

401 Hatasının Yaygın Nedenleri

Nedenler, ziyaretçi tarafından sunucu tarafına doğru:

• Yanlış kullanıcı adı veya parola — en basit neden, özellikle parola sıfırlandıktan sonra
• Süresi dolmuş kimlik doğrulama tokeni — JWT'lerin, OAuth erişim tokenlerinin ve oturum çerezlerinin hepsinin bir süresi vardır
• Eksik Authorization başlığı — istek hiç kimlik bilgisi içermiyordu
• Geçersiz API anahtarı — anahtar iptal edilmiş, yenilenmiş ya da yanlış kopyalanmış
• Yanlış kimlik doğrulama şeması — sunucu Bearer token bekliyor ama Basic geliyor, ya da tersi
• Saat farkı — bir JWT'yi doğrulayan sunucu ile onu üreten sunucu (ya da JWT'yi imzalayan sizin makineniz) saat konusunda anlaşamıyor; birçok kitaplık hiç tolerans tanımaz
• CORS ön kontrol isteği — tarayıcının OPTIONS kontrolü hiçbir zaman kimlik bilgisi taşımaz, bu yüzden bunları isteyen bir sunucu 401 yanıtı verir ve asıl istek hiç gönderilmez
• Eski bir oturum — tarayıcı, sunucunun çoktan sonlandırdığı bir oturum çerezi gönderiyor
• Aradaki bir şey başlığı düşürüyor — Apache, aksi söylenmedikçe Authorization'ı PHP-FPM ve CGI betiklerinden saklar; CloudFront varsayılan olarak GET ve HEAD isteklerinden çıkarır; bir uygulamanın önündeki nginx Basic kimlik doğrulaması ise onu devralır
• Kilitlenmiş veya iptal edilmiş kimlik bilgileri — çok fazla başarısız deneme hesabı kilitleyebilir (bazı API'ler buna bunun yerine 429 Too Many Requests ile yanıt verir)

Ziyaretçi Olarak 401 Hatası Nasıl Düzeltilir

Erişmek istediğiniz bir web sitesinde 401 hatasıyla karşılaşıyorsanız, sorun neredeyse her zaman giriş bilgilerinizle ilgilidir. Bu adımları sırasıyla takip edin.

1. Giriş Bilgilerinizi Kontrol Edin

401 hatasının en yaygın nedeni basitçe yanlış kimlik bilgileridir. Site bir giriş penceresi veya formu gösteriyorsa, kullanıcı adınızı ve parolanızı tekrar kontrol edin.

Yaygın hatalar: Caps Lock açık, eski bir parola kullanıyorsunuz (özellikle yakın zamanda yapılan bir sıfırlamadan sonra) veya yanlış hesaba giriş yapıyorsunuz. Bir parola yöneticiniz varsa, yazım hatalarını önlemek için kimlik bilgilerini otomatik doldurmesini sağlayın.

2. Tarayıcı Önbelleğini ve Çerezleri Temizleyin

Tarayıcınız süresi dolmuş bir oturum çerezi gönderiyor olabilir. Sitenin çerezlerini silmek, sitenin yeniden giriş istemesini sağlar.

Türkçe Chrome'da Ctrl+Shift+Delete (Mac'te Cmd+Shift+Delete) ile “Tarama verilerini sil” penceresini açın, zaman aralığını “Son bir saat” yerine “Tüm zamanlar” yapın, “Çerezler ve diğer site verileri” ile “Önbelleğe alınan resimler ve dosyalar” seçeneklerini işaretleyip “Verileri sil”e tıklayın. Bu, sizi tüm sitelerden çıkarır. Yalnızca tek bir site için: adresin solundaki “Site bilgilerini görüntüle” → “Çerezler ve site verileri” → “Cihaz üzerindeki site verilerini yönetin”. Diğer tarayıcılar için adımlar (İngilizce etiketlerle):

Chrome, Edge, Firefox: Ctrl+Shift+Delete (Cmd+Shift+Delete on a Mac)
  → Time range: All time → Cookies and site data + Cached files → Delete / Clear
  (this signs you out of every site; the per-site option below doesn't)
Safari: Settings → Privacy → Manage Website Data → the site → Remove
One site in Chrome: the icon left of the address → Site settings → Delete data

Temizledikten sonra tarayıcıyı tamamen kapatın (sadece sekmeyi değil), yeniden açın ve sayfaya tekrar gidin. Yeni bir giriş istemi görmelisiniz.

3. Gizli veya Özel Modu Deneyin

URL'yi bir gizli pencerede (Chrome) veya özel pencerede (Firefox/Safari) açın. Bu, tüm önbellekteki çerezleri, uzantıları ve kayıtlı kimlik bilgilerini atlar.

Sayfa gizli modda çalışıyorsa ancak normal tarayıcınızda çalışmıyorsa, sorun önbellekteki bir çerez veya kimlik doğrulamayı engelleyen bir tarayıcı uzantısıdır. Sorumluyu bulmak için uzantıları tek tek devre dışı bırakın.

4. URL'yi Doğrulayın

Doğru URL'yi ziyaret ettiğinizden emin olun. Bazı sunucular, yolun kendisi yanlış olsa bile kimlik doğrulaması gerektiren yollar için 401 döndürür. Girmeniz amaçlanmamış, kısıtlı bir alana erişmeye çalışıyor olabilirsiniz.

Sayfanın farklı bir URL'de herkese açık bir sürümü olup olmadığını kontrol edin. Örneğin example.com/admin/ 401 döndürürken example.com/ herkese açık olabilir.

Sitenin hiç çalışıp çalışmadığından emin değil misiniz? Site Çöktü mü Kontrolü siteyi 11 noktadan açar; böylece bir giriş sorununu kesintiden ayırabilirsiniz.

Geliştirici Olarak 401 Hatası Nasıl Düzeltilir

API'lerle çalışan geliştiriciler için 401 hataları genellikle Authorization başlığı, token formatı veya kimlik bilgisi yaşam döngüsüyle ilgilidir. En yaygın çözümler bunlardır.

5. Authorization Başlığını Doğrulayın

Geliştiricilerin en sık yaptığı hata, hatalı biçimlendirilmiş bir Authorization başlığıdır. Sunucu WWW-Authenticate başlığı gönderdiğinde, beklediği şemayı bu başlık belirtir; birçok JSON API (örneğin GitHub ve OpenRouter) onu göndermez ve sorunu yanıt gövdesinde açıklar.

Başlığınızın gereken biçime uyduğunu kontrol edin. En yaygın şemalar Bearer (tokenler için) ve Basic'tir (Base64 ile kodlanmış kullanıcı adı:parola).

# Bearer token authentication (most APIs)
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." https://api.example.com/data

# Basic authentication (username:password in Base64)
curl -u "username:password" https://api.example.com/data
# Equivalent to:
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" https://api.example.com/data

# Common mistakes that cause 401:
# Missing "Bearer " prefix:  Authorization: eyJhbGci...  ← WRONG
# Extra space:               Authorization: Bearer  eyJ... ← many servers reject it
# Wrong scheme:              Authorization: Basic eyJhbGci... ← WRONG

Ardından 401 yanıtındaki WWW-Authenticate başlığını okuyun: sunucunun beklediği şemayı söyler. DNS Robot'un HTTP Başlık Kontrolü yanıtın tamamını gösterir.

6. API Anahtarı Geçerliliğini Kontrol Edin

API anahtarları; anahtar yenilendiğinde veya iptal edildiğinde, hesap askıya alındığında ya da düşürüldüğünde, ya da test anahtarı canlı ortamda kullanıldığında çalışmayı bırakır. (Hız sınırı 429 döndürür, bir uç noktaya erişimi olmayan anahtar ise genellikle 403 alır.)

Anahtarın sağlayıcının panelinde hâlâ etkin olduğunu kontrol edin, sonra doğrudan test edin:

# Test a key: print only the status code (a real GET; some APIs reject HEAD)
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/me
# 200 = the key works
# 401 = the key is missing, wrong, revoked or expired
# 403 = the key works but isn't allowed to use this endpoint

# Common slips:
# 1. A space or newline after the key in .env:   API_KEY="abc123 "
# 2. The test key in production, or the reverse
# 3. An empty variable, so the header is just "Authorization: Bearer"

7. Token Süresi Dolma ve Yenileme

JWT'lerin ve OAuth erişim tokenlerinin ömrü sınırlıdır, genellikle 15 dakikadan 24 saate kadar. Süre dolunca, yeni bir token alana kadar her API çağrısı 401 döndürür.

Bir yenileme tokeniniz varsa (OAuth 2.0 ve çoğu JWT kurulumu) onu yeni bir erişim tokeniyle değiştirin; yoksa yeniden giriş yapın.

# Read a JWT's payload (tokens use base64url, so plain base64 -d often fails)
python3 -c 'import sys,base64,json; p=sys.argv[1].split(".")[1]; print(json.dumps(json.loads(base64.urlsafe_b64decode(p+"==")),indent=2))' "$TOKEN"
# "exp" is a Unix timestamp; compare it with: date +%s

# OAuth 2.0: get a new access token with the refresh token
curl -X POST https://auth.example.com/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

8. CORS Preflight Sorunlarını Düzeltme

Bir web sayfası başka bir alan adındaki API'yi Authorization başlığıyla çağırdığında, tarayıcı önce bir OPTIONS ön kontrol isteği gönderir ve bu istek hiçbir zaman kimlik bilgisi taşımaz. Sunucu OPTIONS için kimlik doğrulaması isterse 401 yanıtı verir, ön kontrol başarısız olur ve tarayıcı bir CORS hatası bildirir: asıl istek hiç gönderilmez.

Çözüm: CORS etkin uç noktalarda OPTIONS isteklerini kimlik doğrulaması olmadan geçirin.

# Nginx — allow OPTIONS requests without auth
location /api/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin https://app.example.com;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
        add_header Access-Control-Allow-Headers "Authorization, Content-Type";
        add_header Access-Control-Max-Age 86400;
        return 204;
    }

    # CORS header on every other answer, the 401 included, or the browser reports a CORS error
    add_header Access-Control-Allow-Origin https://app.example.com always;

    # Normal auth for other methods
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Site Sahibi Olarak 401 Hatası Nasıl Düzeltilir

Ziyaretçileriniz veya kullanıcılarınız 401 hataları bildiriyorsa, sorun sunucunuzun kimlik doğrulama yapılandırmasındadır. Bu kontrolleri yapın.

9. Sunucu Kimlik Doğrulama Yapılandırmasını İnceleyin

Kimlik doğrulamanın yalnızca ihtiyaç duyan yollarda etkin olduğundan emin olun. Sık yapılan bir hata, yalnızca belirli yollar giriş gerektirmesi gerekirken tüm bir dizini veya siteyi korumaktır.

nginx'te auth_basic yönergelerinizi, Apache'de AuthType ve Require yönergelerini kontrol edin. Node.js/Express'te middleware sırasına bakın: herkese açık yollarınızdan önce kaydedilen bir app.use(auth) onları da korur; bu yüzden önce herkese açık yolları kaydedin ya da kimlik doğrulamayı yalnızca korumalı yönlendiriciye bağlayın.

# Nginx — WRONG: protects everything, including public pages
server {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    # All pages now require login — including your homepage!
}

# Nginx — CORRECT: only protect admin routes
server {
    location / {
        # Public — no auth required
    }
    location /admin/ {
        auth_basic "Admin Area";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

10. .htaccess Kimlik Doğrulama Kurallarını Kontrol Edin

Apache'de .htaccess dosyaları bir dizin için Basic veya Digest kimlik doğrulamasını açabilir. Herkese açık bir dizinde AuthType ve Require yönergeleri olan bir .htaccess varsa, her ziyaretçi 401 giriş istemi alır.

Etkilenen dizinde ve tüm üst dizinlerde .htaccess dosyalarını arayın — Apache, yoldaki her .htaccess dosyasının kurallarını uygular.

# Find all .htaccess files with auth rules
find /var/www/html -name '.htaccess' -exec grep -l 'AuthType\|AuthUserFile\|Require valid-user' {} \;

# Example .htaccess that causes 401 for everyone:
# AuthType Basic
# AuthName "Restricted Area"
# AuthUserFile /etc/apache2/.htpasswd
# Require valid-user

# Fix: remove auth lines from public directories,
# or move them to the specific /admin/.htaccess only

11. Authorization Başlığının Uygulamanıza Ulaştığından Emin Olun

İstemci doğru kimlik bilgilerini gönderiyor, ama uygulama onları hiç görmüyor. Başlığın kaybolduğu yerler:

nginx, Authorization başlığını varsayılan olarak arka uca iletir, bu yüzden ek satırlara gerek yoktur; ancak aynı location auth_basic kullanıyorsa nginx'in girişi başlığı devralır (yukarıdaki nginx bölümüne bakın). Apache, CGIPassAuth'u açmadıkça (Apache 2.4.13+) Authorization'ı PHP-FPM ve CGI betiklerinden saklar; bu, Apache arkasındaki WordPress ve Laravel API'lerinde 401'in klasik nedenidir.

# Apache 2.4.13+ (inside a <Directory> block, or .htaccess): pass Authorization to PHP-FPM and CGI
CGIPassAuth On

# Older Apache: copy it into an environment variable instead
SetEnvIf Authorization "(.+)" HTTP_AUTHORIZATION=$1

HTTP Başlıklarıyla 401 Hatalarını Ayıklama

401'i teşhis etmenin en hızlı yolu yanıtı okumaktır: sunucu gönderiyorsa WWW-Authenticate başlığı hangi girişi istediğini söyler, JSON API'ler ise hatayı genellikle gövdede açıklar.

DNS Robot'un HTTP Başlık Kontrolü'nü kullanın (401 yalnızca bir yönlendirmeden sonra görünüyorsa Yönlendirme Kontrolü hangi adımın onu verdiğini gösterir) ya da terminalde curl kullanın:

# Print the response headers of a real GET
curl -sS -D - -o /dev/null https://api.example.com/protected-endpoint

# A 401 often carries one of:
# WWW-Authenticate: Bearer realm="api", error="invalid_token"
# WWW-Authenticate: Basic realm="Admin Area"

# It tells you:
# - the scheme (Bearer, Basic, Digest, Negotiate)
# - the realm (which area is protected)
# - for Bearer tokens, the error: invalid_request, invalid_token or insufficient_scope

WWW-Authenticate Bearer diyorsa token, Basic diyorsa kullanıcı adı ve parola gerekir. error="invalid_token", tokenin süresinin dolduğu, iptal edildiği, bozuk olduğu ya da başka bir nedenle geçersiz olduğu anlamına gelir. Hiç başlık yok mu? Yanıt gövdesini okuyun: birçok API nedeni orada belirtir.

401 Hatası SEO'yu Etkiler mi?

Herkese açık bir sayfadaki 401, sayfayı Google'dan çıkarır. Google, 429 dışındaki tüm 4xx kodlarına aynı şekilde davranır: tarayıcı içeriğin var olmadığını bildirir ve dizine eklenmiş bir URL kaldırılır (Google'ın tarama belgeleri).

Giriş gerektirmesi gereken sayfalardaki (yönetim panelleri, kontrol panelleri, API'ler) 401'ler normaldir: Google bunlar yüzünden siteyi cezalandırmaz. Yalnızca Googlebot'u yavaşlatmak için 401 veya 403 kullanmayın; Google'a göre bunların tarama hızına etkisi yoktur.

Sorun, herkese açık olması gereken sayfalardaki 401'dir; genellikle tüm siteye uygulanan kimlik doğrulamasından ya da herkese açık yollarda kimlik bilgisi isteyen bir CDN veya proxy kuralından kaynaklanır.

401 Hatalarını Nasıl Önlersiniz

Önleme, sonradan debug etme zahmetinden kurtarır. Uygulamalarınızda ve web sitelerinizde 401 hatalarını en aza indirmek için bu uygulamaları takip edin.

• Token yenilemeyi otomatikleştirin — eskileri dolmadan yeni erişim tokenlerini sessizce almak için yenileme tokenleri kullanın
• Kimlik doğrulama kapsamını doğru belirleyin — yalnızca gerçekten kimlik doğrulaması gereken yolları koruyun, herkese açık sayfaları açık bırakın
• Açık hata mesajları verin — 401 ile birlikte yalnızca durum kodunu değil, yararlı bir JSON hata gövdesi de döndürün
• Kimlik doğrulama hatalarını izleyin — kimlik bilgisi sorunlarına ya da saldırılara işaret edebilecek 401 yanıtı artışları için uyarılar kurun
• Sunucu saatlerini eşitleyin — JWT'lerin saat farkı yüzünden reddedilmemesi için NTP ile tüm sunucuları UTC'ye birkaç saniye içinde tutun
• HTTP Başlık Kontrolü ile test edin — herkese açık sayfaların 200, korumalı sayfaların beklendiği gibi 401 döndürdüğünü düzenli olarak doğrulayın
• Kimlik doğrulama şemanızı belgeleyin — beklenen Authorization başlığı biçimini API belgelerinizde açıkça belirtin
• CORS ön kontrolünü yönetin — API uç noktalarında OPTIONS isteklerine her zaman kimlik doğrulaması olmadan izin verin