Błąd 401 Unauthorized: co oznacza i jak go naprawić

Czym jest błąd 401 Unauthorized?

Błąd 401 Unauthorized oznacza, że serwer chce, abyś potwierdził(-a), kim jesteś, a Twoje żądanie tego nie zrobiło albo dołączone dane zostały odrzucone. Brak hasła, błędne hasło, wygasły token czy brakujący klucz API kończą się tak samo.

Standard HTTP definiuje go jako żądanie, któremu „brakuje prawidłowych danych uwierzytelniających dla zasobu docelowego”, a serwer wysyłający 401 MUSI dołączyć nagłówek WWW-Authenticate, który wskazuje akceptowany schemat logowania (RFC 9110 §15.5.2).

Najprościej: serwer pyta „kim jesteś?”, zanim Cię wpuści.

Jak wygląda błąd 401

Wygląd strony zależy od serwera i aplikacji:

• 401 Unauthorized — standardowy wiersz statusu i sformułowanie w większości aplikacji
• 401 Authorization Required — tytuł wbudowanej strony 401 serwera nginx, z napisem „nginx” (zwykle z numerem wersji) pod spodem (kod źródłowy nginx); te same słowa pokazują stare serwery Apache 2.2
• Unauthorized · This server could not verify that you are authorized to access the document requested — domyślna strona Apache
• 401 - Unauthorized: Access is denied due to invalid credentials — IIS; szczegółowa strona (widoczna tylko na samym serwerze) i dziennik IIS podają przyczynę jako 401.1, 401.2 lub 401.3: nieudane logowanie, konfiguracja serwera lub uprawnienia do plików
• Okno logowania w przeglądarce — gdy serwer żąda uwierzytelniania HTTP Basic lub Digest albo (w IIS i sieciach firmowych) NTLM lub Negotiate
• Ta strona nie działa · HTTP ERROR 401 — Chrome, gdy odpowiedź 401 nie ma własnej strony
• JSON z API, na przykład {"error":{"message":"Missing Authentication header","code":401}}

Przeglądarki pokazują okno logowania tylko dla tych schematów. Interfejsy API z tokenami („Bearer”) nigdy go nie wywołują: ich 401 wraca jako JSON, który obsługuje aplikacja. Strony z formularzem logowania zwykle odsyłają niezalogowanego odwiedzającego na stronę logowania przekierowaniem 302, a nie błędem 401.

„401 Authorization Required” w nginx

Ten tytuł pochodzi z wbudowanej strony 401 serwera nginx. Pojawia się, gdy lokalizacja jest chroniona dyrektywą auth_basic, a żądanie nie zawierało nazwy użytkownika i hasła albo zawierało błędne; anulowanie okna logowania w przeglądarce też pokazuje tę stronę.

Jako odwiedzający odśwież stronę i wpisz nazwę użytkownika oraz hasło, które podał właściciel witryny. Nie są one związane z żadnym kontem w serwisie: uwierzytelnianie Basic sprawdza plik z hasłami na serwerze.

Jako właściciel witryny w ten sposób ustawia się ochronę i zostawia otwartą jedną ścieżkę:

# 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

Nadal 401 mimo poprawnego hasła? Sprawdź, czy użytkownik jest w pliku (htpasswd -c nadpisuje plik, usuwając wcześniejszych użytkowników) oraz czy aplikacja za nginx nie potrzebuje też nagłówka Authorization: logowanie Basic w nginx i tokeny Bearer aplikacji używają tego samego nagłówka, więc aplikacja dostaje dane z nginx i je odrzuca.

401 vs 403: jaka jest różnica?

Kody 401 i 403 są często mylone. Krótko: 401 znaczy „nie wiem, kim jesteś”, a 403 „nie wpuszczę Cię”, niezależnie od tego, czy problemem jest tożsamość.

Praktyczna zasada: jeśli problem rozwiązałoby podanie właściwej nazwy użytkownika i hasła (lub klucza API), serwer powinien zwrócić 401. Jeśli użytkownik jest już uwierzytelniony, ale po prostu nie ma dostępu do zasobu, serwer powinien zwrócić 403 Forbidden.

Najczęstsze przyczyny błędów 401

Przyczyny, od strony odwiedzającego po stronę serwera:

• Błędna nazwa użytkownika lub hasło — najprostsza przyczyna, zwłaszcza po resecie hasła
• Wygasły token uwierzytelniający — tokeny JWT, tokeny dostępu OAuth i pliki cookie sesji mają określony czas ważności
• Brak nagłówka Authorization — żądanie nie zawierało żadnych danych uwierzytelniających
• Nieprawidłowy klucz API — klucz został unieważniony, zrotowany lub źle skopiowany
• Zły schemat uwierzytelniania — serwer oczekuje tokena Bearer, a dostał Basic, albo odwrotnie
• Rozbieżność zegarów (clock skew) — serwer sprawdzający JWT i ten, który go wystawił (lub Twój komputer, jeśli to on podpisuje JWT), mają różny czas; wiele bibliotek nie dopuszcza żadnego marginesu
• Żądanie CORS preflight — kontrola OPTIONS wysyłana przez przeglądarkę nigdy nie zawiera danych logowania, więc serwer, który ich wymaga, odpowiada 401, a właściwe żądanie w ogóle nie jest wysyłane
• Nieaktualna sesja — przeglądarka wysyła plik cookie sesji, którą serwer już zakończył
• Coś po drodze usuwa nagłówek — Apache ukrywa Authorization przed PHP-FPM i skryptami CGI, jeśli nie ustawisz inaczej, CloudFront domyślnie usuwa go z żądań GET i HEAD, a uwierzytelnianie Basic w nginx przed aplikacją przejmuje ten nagłówek
• Zablokowane lub unieważnione dane logowania — zbyt wiele nieudanych prób może zablokować konto (niektóre API odpowiadają wtedy 429 Too Many Requests)

Jak naprawić błąd 401 jako odwiedzający

Jeśli widzisz błąd 401 na stronie, do której próbujesz wejść, problem prawie zawsze dotyczy Twoich danych logowania. Wykonaj poniższe kroki po kolei.

1. Sprawdź dane logowania

Najczęstszą przyczyną błędu 401 są po prostu błędne dane logowania. Jeśli strona pokazuje okno logowania lub formularz, sprawdź dokładnie nazwę użytkownika i hasło.

Typowe pomyłki: włączony Caps Lock, stare hasło (zwłaszcza po niedawnej zmianie) albo logowanie na niewłaściwe konto. Jeśli korzystasz z menedżera haseł, pozwól mu wypełnić dane automatycznie, żeby uniknąć literówek.

2. Wyczyść pamięć podręczną i pliki cookie przeglądarki

Przeglądarka może wysyłać wygasły plik cookie sesji. Usunięcie plików cookie witryny sprawi, że poprosi o ponowne zalogowanie.

W Chrome z polskim interfejsem otwórz okno „Usuń dane przeglądania” skrótem Ctrl+Shift+Delete (Cmd+Shift+Delete na Macu), wybierz zakres czasowy „Od początku” zamiast „Ostatnia godzina”, zaznacz „Pliki cookie i inne dane witryn” oraz „Obrazy i pliki w pamięci podręcznej” i kliknij „Usuń dane”. To wyloguje Cię ze wszystkich witryn. Aby usunąć dane tylko jednej witryny: Więcej → Ustawienia → Prywatność i bezpieczeństwo → Pliki cookie innych firm → „Zobacz wszystkie dane witryn i ich uprawnienia”, wyszukaj nazwę witryny i kliknij Usuń. Kroki dla innych przeglądarek (nazwy angielskie):

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

Po wyczyszczeniu całkowicie zamknij przeglądarkę (nie tylko kartę), otwórz ją ponownie i wejdź na stronę jeszcze raz. Powinno pojawić się nowe żądanie logowania.

3. Spróbuj trybu incognito lub prywatnego

Otwórz adres URL w oknie incognito (Chrome) lub prywatnym (Firefox/Safari). Pomija ono zapisane pliki cookie, rozszerzenia i zapamiętane dane logowania.

Jeśli strona działa w trybie incognito, ale nie w zwykłej przeglądarce, winny jest zapisany plik cookie albo rozszerzenie, które zakłóca uwierzytelnianie. Wyłączaj rozszerzenia po jednym, aby znaleźć sprawcę.

4. Zweryfikuj adres URL

Upewnij się, że odwiedzasz właściwy adres URL. Niektóre serwery zwracają 401 dla ścieżek wymagających uwierzytelnienia, nawet jeśli sama ścieżka jest błędna. Możliwe, że próbujesz wejść do obszaru zastrzeżonego, który nie jest dla Ciebie.

Sprawdź, czy istnieje publiczna wersja strony pod innym adresem. Na przykład example.com/admin/ może zwracać 401, podczas gdy example.com/ jest publicznie dostępne.

Nie masz pewności, czy strona w ogóle działa? Sprawdź ją narzędziem Sprawdzanie, czy strona działa: otwiera ją z 11 miejsc, więc odróżnisz problem z logowaniem od awarii.

Jak naprawić błąd 401 jako deweloper

Dla deweloperów pracujących z API błąd 401 zwykle wiąże się z nagłówkiem Authorization, formatem tokena lub cyklem życia danych uwierzytelniających. Oto najczęstsze rozwiązania.

5. Zweryfikuj nagłówek Authorization

Najczęstszy błąd deweloperów to źle sformatowany nagłówek Authorization. Gdy serwer wysyła nagłówek WWW-Authenticate, wskazuje on oczekiwany schemat; wiele API JSON (na przykład GitHub i OpenRouter) go pomija i opisuje problem w treści odpowiedzi.

Sprawdź, czy nagłówek ma wymagany format. Najczęstsze schematy to Bearer (dla tokenów) i Basic (nazwa:hasło zakodowane w Base64).

# 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

Następnie przeczytaj nagłówek WWW-Authenticate w odpowiedzi 401: wskazuje on schemat oczekiwany przez serwer. Checker nagłówków HTTP od DNS Robot pokazuje pełną odpowiedź.

6. Sprawdź ważność klucza API

Klucze API przestają działać, gdy klucz zostanie zrotowany lub unieważniony, konto zawieszone albo obniżone do niższego planu, lub gdy klucz testowy trafi na produkcję. (Limit zapytań daje 429, a klucz bez dostępu do danego endpointu zwykle dostaje 403.)

Sprawdź w panelu dostawcy, czy klucz jest nadal aktywny, a następnie przetestuj go bezpośrednio:

# 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. Obsługa wygasania i odświeżania tokenów

Tokeny JWT i tokeny dostępu OAuth mają ograniczony czas życia, zwykle od 15 minut do 24 godzin. Po wygaśnięciu każde wywołanie API zwraca 401, dopóki nie dostaniesz nowego tokena.

Jeśli masz token odświeżania (OAuth 2.0 i większość konfiguracji JWT), wymień go na nowy token dostępu; jeśli nie, zaloguj się ponownie.

# 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. Napraw problemy z CORS preflight

Gdy strona internetowa wywołuje API w innej domenie z nagłówkiem Authorization, przeglądarka najpierw wysyła żądanie preflight OPTIONS, które nigdy nie zawiera danych logowania. Jeśli serwer wymaga uwierzytelnienia dla OPTIONS, odpowiada 401, preflight kończy się niepowodzeniem, a przeglądarka zgłasza błąd CORS: właściwe żądanie nigdy nie zostaje wysłane.

Rozwiązanie: przepuszczaj żądania OPTIONS bez uwierzytelniania w endpointach z włączonym CORS.

# 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;
}

Jak naprawić błąd 401 jako właściciel strony

Jeśli odwiedzający lub użytkownicy zgłaszają błędy 401, problem leży w konfiguracji uwierzytelniania na serwerze. Przejdź przez poniższe kontrole.

9. Sprawdź konfigurację uwierzytelniania serwera

Sprawdź, czy uwierzytelnianie jest włączone tylko dla tras, które go potrzebują. Częsty błąd to ochrona całego katalogu lub witryny, gdy logowania powinny wymagać tylko wybrane ścieżki.

W nginx sprawdź dyrektywy auth_basic; w Apache AuthType i Require. W Node.js/Express sprawdź kolejność middleware: app.use(auth) zarejestrowane przed trasami publicznymi chroni również je, więc rejestruj trasy publiczne najpierw albo podpinaj uwierzytelnianie tylko do chronionego routera.

# 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. Sprawdź reguły uwierzytelniania .htaccess

W Apache pliki .htaccess mogą włączać uwierzytelnianie Basic lub Digest dla katalogu. Jeśli publiczny katalog ma .htaccess z dyrektywami AuthType i Require, każdy odwiedzający dostaje 401 z oknem logowania.

Poszukaj plików .htaccess w danym katalogu i we wszystkich katalogach nadrzędnych: Apache stosuje reguły z każdego .htaccess na ścieżce.

# 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. Upewnij się, że nagłówek Authorization dociera do aplikacji

Klient wysyła poprawne dane, ale aplikacja ich nie widzi. Gdzie ginie nagłówek:

nginx domyślnie przekazuje Authorization do backendu, więc nie potrzeba dodatkowych linii; ale jeśli ta sama lokalizacja używa auth_basic, logowanie nginx przejmuje nagłówek (patrz sekcja o nginx wyżej). Apache ukrywa Authorization przed PHP-FPM i skryptami CGI, dopóki nie włączysz CGIPassAuth (Apache 2.4.13+), klasycznej przyczyny błędów 401 w API WordPressa i Laravela za Apache.

# 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

Debugowanie błędów 401 za pomocą nagłówków HTTP

Najszybszy sposób diagnozy 401 to przeczytanie odpowiedzi: nagłówek WWW-Authenticate, jeśli serwer go wysyła, mówi, jakiego logowania oczekuje, a API JSON zwykle opisują błąd w treści.

Użyj Checkera nagłówków HTTP od DNS Robot (jeśli 401 pojawia się dopiero po przekierowaniu, Checker przekierowań pokaże, który krok go zwraca) albo curl w terminalu:

# 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

Jeśli WWW-Authenticate zawiera Bearer, potrzebny jest token; jeśli Basic, nazwa użytkownika i hasło. error="invalid_token" oznacza, że token wygasł, został unieważniony, jest uszkodzony lub z innego powodu nieprawidłowy. Brak nagłówka? Przeczytaj treść odpowiedzi: wiele API podaje tam przyczynę.

Czy błąd 401 wpływa na SEO?

Błąd 401 na publicznej stronie usuwa ją z Google. Google traktuje wszystkie kody 4xx poza 429 tak samo: robot zgłasza, że treść nie istnieje, a zindeksowany adres URL zostaje usunięty (dokumentacja Google o skanowaniu).

Błędy 401 na stronach, które mają wymagać logowania (panele administracyjne, dashboardy, API), są normalne: Google nie karze za nie witryny. Tylko nie używaj 401 ani 403, żeby spowolnić Googlebota; według Google nie wpływają one na częstotliwość skanowania.

Problemem jest 401 na stronach, które powinny być publiczne, zwykle przez uwierzytelnianie nałożone na całą witrynę albo regułę CDN lub proxy żądającą danych logowania na publicznych ścieżkach.

Jak zapobiegać błędom 401

Zapobieganie oszczędza późniejszego debugowania. Stosuj te praktyki, aby ograniczyć błędy 401 w aplikacjach i witrynach.

• Wdróż automatyczne odświeżanie tokenów — używaj tokenów odświeżania, aby po cichu pobierać nowe tokeny dostępu, zanim wygasną
• Ustaw właściwe zakresy uwierzytelniania — chroń tylko trasy, które naprawdę tego wymagają, i zostaw strony publiczne otwarte
• Zwracaj czytelne komunikaty błędów — oprócz 401 zwracaj pomocną treść JSON, a nie tylko kod statusu
• Monitoruj błędy uwierzytelniania — ustaw alerty na skoki odpowiedzi 401, które mogą wskazywać problemy z danymi logowania lub ataki
• Synchronizuj zegary serwerów — używaj NTP, aby wszystkie serwery różniły się od UTC najwyżej o kilka sekund, co zapobiega odrzucaniu JWT z powodu rozbieżności zegarów
• Testuj za pomocą Checkera nagłówków HTTP — regularnie sprawdzaj, czy strony publiczne zwracają 200, a chronione 401, jak należy
• Udokumentuj schemat uwierzytelniania — jasno opisz w dokumentacji API oczekiwany format nagłówka Authorization
• Obsłuż CORS preflight — zawsze przepuszczaj żądania OPTIONS bez uwierzytelniania w endpointach API