HTTP 401 Unauthorized

Quick reference

What HTTP 401 means

RFC 9110 defines 401 as indicating that the request has not been applied because it lacks valid authentication credentials for the target resource. The server must send a WWW-Authenticate header containing at least one challenge applicable to the target resource.

The name "Unauthorized" is historically confusing. In practice, 401 means "unauthenticated" — the server does not know who you are. 403 Forbidden means "authenticated but not permitted" — the server knows who you are but will not allow the action. This distinction is fundamental to implementing correct authentication and authorization responses.

A 401 response tells the client: provide credentials (or different credentials) and try again. This is different from 403, which tells the client: providing credentials will not help — access is denied regardless.

The WWW-Authenticate header

Every 401 response must include a WWW-Authenticate header. This header describes the authentication scheme(s) the server accepts. Without it, the client has no way to know how to authenticate.

Common authentication challenges:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Admin Area"

The realm attribute describes the protection space — it helps users and clients understand what resource they are authenticating for. For Bearer token APIs, additional attributes like error and error_description (from RFC 6750) provide more specific failure reasons.

Common causes

Missing Authorization header

The request did not include any authentication credentials. The client needs to add an Authorization header with a valid token, API key, or Basic auth credentials before retrying.

Expired token or session

JWT tokens, OAuth access tokens, and session cookies all expire. A 401 on an endpoint that was working previously often indicates token expiry. The client should refresh the token (using a refresh token if available) and retry the request.

Invalid or malformed credentials

The Authorization header is present but its value is wrong — a typo in the API key, a Base64-encoding error in Basic auth, or a corrupted token. Check the exact value being sent against what the server expects.

Wrong authentication scheme

Sending Bearer authentication to an endpoint that expects Basic auth, or vice versa. The WWW-Authenticate header in the 401 response tells you which scheme is expected.

Token revoked or invalidated

Tokens can be revoked server-side by logging out from another device, changing a password, rotating API keys, or admin action. A revoked token produces a 401 even if the token itself has not expired. The client must obtain new credentials.

401 vs 403 — the critical distinction

The practical impact: if you are building an API, return 401 when the client is not authenticated (no credentials, invalid credentials, expired token). Return 403 when the client is authenticated but the authenticated identity does not have permission to perform the requested action.

Returning 401 instead of 403 reveals that a resource exists (the server is checking auth before checking permissions). Some security-sensitive APIs return 404 instead of 403 to avoid confirming resource existence to unauthorized clients.

How to fix a 401 error

1. Read the WWW-Authenticate header. It describes the expected authentication scheme and may include an error code that explains what went wrong.
2. Check that credentials are present. Confirm the Authorization header is being sent in the request. Use a tool like curl with -v or browser DevTools to verify.
3. Check token expiry. If using JWT or OAuth, decode the token and check the exp claim. If expired, refresh it.
4. Verify the credential format. Basic auth requires Authorization: Basic <base64(user:pass)>. Bearer tokens require Authorization: Bearer <token>. Misformatted values produce 401 even if the underlying credential is valid.
5. Re-authenticate. If the token is revoked or the session is invalid, log in again to obtain fresh credentials.

FAQ

What does HTTP 401 Unauthorized mean?

HTTP 401 means the server requires authentication and the request did not provide valid credentials. Despite the name, it is about authentication (who you are), not authorization (what you can do). Provide valid credentials and retry.

What is the difference between 401 and 403?

401 means unauthenticated — the server does not know who you are. 403 means unauthorized — the server knows who you are but is denying access. Credentials will fix a 401; they will not fix a 403.

Why does my request keep returning 401 after I provide credentials?

Check that the credentials are formatted correctly, not expired, and match exactly what the server expects. Check the WWW-Authenticate header for an error attribute that describes the specific failure reason.

Should I retry after a 401?

Yes — after refreshing or correcting your credentials. Do not retry the same request with the same credentials; it will produce the same 401. Fix the credentials first.

Related resources

On this site: HTTP 401 Unauthorized — full guide · HTTP 403 Forbidden · HTTP 407 Proxy Authentication Required · HTTP 511 Network Authentication Required · All 4xx client errors

Comparisons: 401 vs 403 · 400 vs 401

Standards: RFC 9110 §15.5.2 · IANA HTTP Status Code Registry · MDN Web Docs: 401