7

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.

Frank Rosario
  • 2,512
  • 5
  • 31
  • 47

4 Answers4

2

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

Edgar
  • 1,174
  • 8
  • 9
  • I think it's a very interesting and absolutely valid strategy. I am also pretty sure it is generally a very sound approach too, beyond specifically *login* sessions -- I'd say it's a good way to implement any kind of client-controlled sessions. – Armen Michaeli May 26 '19 at 11:10
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."

David Harris
  • 2,332
  • 1
  • 13
  • 25
  • 1
    Then again, it *assumes a resource* for which authorization and by extension authentication is required, has failed, or has not yet been provided. Obtaining an authentication token itself is not a such resource, returning `401 Unauthorized` when submitting e.g. wrong password to obtain an authentication token is in my opinion ill fitted and is "surprising" to the client and thus a bad choice. E.g., I am submitting credentials for authentication and get back from server "you are unauthorized". Like, I am *unauthorized to actually authenticate*? – Armen Michaeli May 29 '18 at 09:34
0

How about 400 Bad Request? As in, the parameters you specified (incorrect login credentials) are not valid for the action you tried to perform (creating a login session).

Wyzard
  • 33,849
  • 3
  • 67
  • 87
  • 2
    `400 Bad Request` is reserved for cases where the server could not *understand* the request and/or could not [process](https://tools.ietf.org/html/rfc7231#section-6.5.1) it -- if a server parses the request, extracting the credentials and testing them for validity before concluding they do not correspond to any valid login session, all as part of normal (non-exceptional) login request processing -- then one can hardly say the request could not be understood or processed. In short, "incorrect login credentials" is not the same condition as "can't parse credentials". – Armen Michaeli May 26 '19 at 11:14
0

200

and the content can be like:

{
  isLoggedIn: false,
  reason: "wrong password"
}

Also, when the login action is executed successfully you can return 201, because you probably have created a session or a token session. The login action di per se will create a session on the server probably so you will return something to use in successive calls.
It's up to you to return a different reason ("user not found", "account blocked") when the provided username/email is wrong (does not exists) or a 404 error.

Alex 75
  • 2,798
  • 1
  • 31
  • 48