Proper status code to return when login fails

Question

I have a RESTful login web service. However, there's been debate internally as to what status code is best to return in the case that a set of credentials passed to it aren't valid. I've been returning 401; but that doesn't seem correct as it implies you have to be logged in already to use the login service. 403 has also been discussed; but that implies you're already authenticated but are restricted from using a given resource. Maybe 404; because a user could not be found with said credentials.

What's the proper status code to return from a login service if the credentials aren't valid?

If it matters, this REST login API is being consumed by both a web app and an iPhone app.

Answer 1

I believe your struggle to find an appropriate HTTP status code is due to the fact that a RESTful login web service is an oxymoron. To wit: RESTful API endpoints expose resources upon which HTTP verbs operate. Logging into a service is a transitional action (e.g. establishing a session or similar). So it is unnatural for your RESTful API to return an HTTP status code for this transitional action.

That being said, you did not specify what the endpoint is, or give clues to how it operates. I can conjecture that a RESTful API login service could, in theory, operate thusly:

RESTful call to to create a session

POST /api/sessions/
response would be
201 - Created
/api/sessions/12345abcdef

And thus the client has 'logged in'. Clearly I am assuming that some credentials would be passed in via headers or query parameters.

And then logging out would be

DELETE /api/sessions/12345abcdef

But I suspect this is a little too way down the path of the pure RESTful path

Answer 2

How about 401 Unauthorized.

I suggest this because the comment on the is page states that this response is to be used "when authentication is required and has failed or has not yet been provided."