401 Unauthorized vs 403 Forbidden: Which is the right status code for when the user has not logged in?

Question

After lots of Googling and Stackoverflowing, it still isn't clear to me because many articles and questions/answers were too general (including 403 Forbidden vs 401 Unauthorized HTTP responses which was not specifically for my use-case).

Question: What's the proper HTTP Status Code when the user has not logged in and requests to see some pages that should be shown only to logged-in users?

Solution 1

The exact satisfying one-time-for-all answer I found is:

Short answer:

401 Unauthorized

---

Description:

While we know first is authentication (has the user logged-in or not?) and then we will go into authorization (does he have the needed privilege or not?), but here's the key that makes us mistake:

But isn’t “401 Unauthorized” about authorization, not authentication?

Back when the HTTP spec (RFC 2616) was written, the two words may not have been as widely understood to be distinct. It’s clear from the description and other supporting texts that 401 is about authentication.

From HTTP Status Codes 401 Unauthorized and 403 Forbidden for Authentication and Authorization (and OAuth).

So maybe, if we want to rewrite the standards! focusing enough on each words, we may refer to the following table:

Status Code | Old foggy naming | New clear naming | Use case
+++++++++++ | ++++++++++++++++ | ++++++++++++++++ | ++++++++++++++++++++++++++++++++++
401         | Unauthorized     | Unauthenticated  | User has not logged-in
403         | Forbidden        | Unauthorized     | User doesn't have enough privilege

Solution 2

It depends on the mechanism you use to perform the login.

The spec for 403 Forbidden says:

The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it. A server that wishes to make public why the request has been forbidden can describe that reason in the response payload (if any).

If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client SHOULD NOT automatically repeat the request with the same credentials. The client MAY repeat the request with new or different credentials. However, a request might be forbidden for reasons unrelated to the credentials.

While 401 Unauthorized is not defined in the main HTTP status codes spec but is in the HTTP Authentication spec and says:

The 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource. The server generating a 401 response MUST send a WWW-Authenticate header field (Section 4.1) containing at least one challenge applicable to the target resource.

---

So if you are using WWW-Authenticate and Authorization headers as your authentication mechanism, use 401. If you are using any other method, then use 403.

Comments

[Quentin]

This is only true if you are using HTTP authentication (and not, for instance, something based on cookies … like OAuth) since you must send a WWW-Authenticate header when you make a 401 response.

[dcangulo]

In my case, I am using it on API. If the user does not supply an API Key I will return 401, and if he supplied an API key but does not have enough privilege I will return 403? Am I correct?

[Merak Marey]

Funny, the user who downvoted my answer was removed...;)

[Polymorphix]

I think this should be the accepted answer. Those RFC quotes are key.

[Polymorphix]

I do not think this is correct. Check out the RFC quotes in @Quentin 's answer below: stackoverflow.com/a/50143750/333331

[Fabien Haddadi]

I don't want to play on words, but maybe 401 should have been tagged "Unauthenticated"? To me, Forbidden and Unauthorised are synonym, IRL. Authenticated means: "we know you are who you say you are".