Signalling authentication failure in a RESTful API

43
votes

I'm writing a small application which exposes a simple REST-ish HTTP API. I'm stuck trying to decide how to signal a failure due to a lack of authorization.

The app does not have an API for authentication, but instead depends upon the presence of a cookie containing a session token obtained by the client via another service. The app verifies the session and uses the identity obtained through the verification process to perform app-specific authorization. There is no way for a client to authenticate directly to this app.

My problem is that the obvious HTTP status code for rejecting unauthorized requests, "401 Unauthorized", is specified in terms of the "WWW-Authenticate" header. See rfc2616 sec 10.4.2.

The response MUST include a WWW-Authenticate header field (section 14.47) containing a challenge applicable to the requested resource.

I can't believe this is an uncommon problem. Is it common to simply overload 401 to include more general uses? What about browsers popping up auth/e dialogs (which incidentally I haven't seen in my testing, so maybe it doesn't happen for POSTs)?

Bottom line: is it OK to use 401 in this context, or is there a better solution?

2
httpresthttp-response-codes
It's not a RESTful API if you are using a cookie. REST services are stateless by definition. – Lukáš Lalinský
Fair point - I changed my description to REST-ish, rather than RESTful. So do you think the answer is either to correctly implement per-request authentication, or abandon my attempt at RESTishness? – j0ni
Hard to say, it depends on your application. The REST approach has some advantages. If you want to keep using the server-side session, I'd return 403 as tvanfosson said. – Lukáš Lalinský

2 Answers

41
votes

Typically, you'd send a 401 if the client can authenticate and solve the problem, but since you don't provide a way to authenticate in the API, I'd suggest returning a 403 error (forbidden) instead. This won't require the header and will indicate to the client that it is unable to access the service.

10
votes

Return something like this:

HTTP/1.1 401 Unauthorized
Location: https://example.com/auth-app/login