Restful design, how to create an authorization service

Question

I'm designing my first RESTful API and am confused about a couple of things.

I am using status codes, nouns and verbs correctly so far, so a POST to http://domain.com/api/contacts will create a new contact etc.

I'm now designing my login form and will not be using HTTP authentication, I'll be getting a json web token and storing it in a cookie. My questions are these..

1) What noun to use for the login service, I assume api/login would be wrong. I'm posting a username and password and expecting a login to occur and a JWT to be send back. I am not creating a user, or getting a user though really, so I'm not sure what to call it.

2) I read in another SO answer that 403 is the correct status code if a call is made to the API and the token is not valid (if it's expired on the front end then the call will never be made), but how do you tell the difference between "login token is not valid" and "login is valid but user is trying to access somebody else's content".

3) If the user is logging in and sends bad credentials, what is the correct status code then? It would seem to be 401 but other answers have said not to use that because browsers will show a password box.

Any help would really be appreciated.

Answer 1

1. POST /auth-tokens
2. If you return an entity with the 403 response, you can include that information
3. If the user is logging in by POSTing to auth-tokens, you can return a 403 Forbidden. From the spec:

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. [...] If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity.

You can use the entity to explain why login failed.