401 Unauthorized error: what it means and how to fix it

02401 vs 403 vs 407: which code applies?

The three codes look alike but ask different parties for different things. For OAuth bearer tokens, RFC 6750 maps its error values onto them: invalid_token goes with 401, insufficient_scope with 403, and a malformed request (invalid_request) with 400 Bad Request.

03What does the WWW-Authenticate header tell you?

The challenge names the scheme, and the scheme tells you what kind of credential the server expects. A Basic challenge makes browsers show their own sign-in prompt; a Bearer challenge is addressed to software, so a browser just displays the page.

Basic is encoding, not encryption: the header in the trace below, dXNlcjpwYXNzd2Q=, is simply user:passwd in base64. RFC 7617 states plainly that Basic is not a secure method unless the connection is protected by TLS.

> GET /basic-auth/user/passwd HTTP/1.1
< HTTP/1.1 401 UNAUTHORIZED
< WWW-Authenticate: Basic realm="Fake Realm"

> Authorization: Basic dXNlcjp3cm9uZw==
< HTTP/1.1 401 UNAUTHORIZED
< WWW-Authenticate: Basic realm="Fake Realm"

> Authorization: Basic dXNlcjpwYXNzd2Q=
< HTTP/1.1 200 OK

04Which layer returned the 401?

Three layers commonly send a 401: the application (a login session or API token check), the web server (password protection such as nginx auth_basic or an Apache .htpasswd), or an authentication proxy or CDN feature in front of both. The page usually gives it away. nginx's built-in page is titled "401 Authorization Required" and arrives with a Basic challenge, while an API answers in JSON with a Bearer challenge.

If the error appears only through the public hostname, compare it with a request straight to the origin using curl --resolve, as described in the status code reference. A 401 that disappears when the request goes straight to the origin points at a reverse proxy or CDN that changed the request on the way.

05Why a 401 appears only behind a proxy or after a redirect

If the credentials are right and the server still says 401, check whether the Authorization header reaches it at all. Three common places lose it.

• The CDN strips it: Amazon CloudFront removes the Authorization header from GET and HEAD requests before forwarding them, unless the distribution is configured to forward it
• The web server hides it from the application: Apache keeps Authorization away from CGI and FastCGI scripts, including PHP-FPM behind mod_proxy_fcgi, unless CGIPassAuth On is set (Apache 2.4.13 and later)
• A redirect drops it: under the Fetch Standard, browsers remove Authorization as soon as a redirect leads to another origin, and curl sends credentials only to the host you first asked unless you use --location-trusted

> GET /redirect-to?url=https%3A%2F%2Fexample.com%2F HTTP/1.1
> Host: httpbin.org
> Authorization: Basic dXNlcjpwYXNzd2Q=
< HTTP/1.1 302 FOUND
< Location: https://example.com/
> GET / HTTP/1.1
> Host: example.com
(no Authorization header on the second request)

06Can a CDN or proxy cache a 401?

Only when its response headers or a cache rule allow it. A 401 is not cacheable by default, so a cache that follows the standard does not store one on its own. Separately, RFC 9111 says a shared cache must not reuse a response to a request that carried an Authorization header for any later request, unless that response explicitly allows shared caching with public, s-maxage or must-revalidate.

Such rules exist. nginx's proxy cache does not consider the Authorization header unless told to, and proxy_cache_valid any caches every status code. In a test on nginx 1.22.1, a 401 cached from an anonymous request was then served to a request with a valid token, and a private 200 cached from an authenticated request was served to an anonymous one. The configuration below fixed both.

# create /var/cache/nginx first if it does not exist; nginx makes only the last level
proxy_cache_path /var/cache/nginx/edge keys_zone=edge:10m;

server {
    listen 80;
    server_name app.example.com;

    location /api/ {
        proxy_pass http://127.0.0.1:8090;
        proxy_cache edge;
        # risky: "proxy_cache_valid any 1m;" would also cache 401, 403 and 500
        proxy_cache_valid 200 301 302 1m;
        proxy_cache_bypass $http_authorization;   # never answer these from cache
        proxy_no_cache $http_authorization;       # never store their responses
    }
}

07401 troubleshooting matrix

08How to fix a 401 error as a visitor

Most 401s that people meet in a browser are expired sessions. Work through these in order:

• Check the URL: an old bookmark can point at an admin or staging area that needs separate credentials
• Sign out and in again, so the site issues a fresh session cookie
• Clear the cookies for that one site, or try a private window to see whether stored data is the cause
• If a browser password prompt appears, the browser remembers what you typed for the rest of the session; after a password change, close the browser completely before trying again
• If the site keeps refusing a password you know is right, ask its operator; repeated attempts can trigger lockouts or rate limits