23

I'm developing an API which will also have an authentication/authorization component.

Anybody, regardless of authentication status, will be able to write (POST), but depending on if you are unauthenticated, authenticated as a normal user or authenticated as an admin and what resource you are trying to access I'm going to return different responses for GET, DELETE and PUT.

I'm trying to figure out the most appropriate response code for a user who isn't authenticated and/or authorized.

Keep in mind http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html:

Unauthorized -> 401

Forbidden -> 403

Method Not Allowed -> 405

Let's use a specific examples:

  • John Doe is unauthenticated, on DELETE should he receive a 401 or a 405?
  • Amy is authenticated but not authorized, on DELETE should she receive a 403 or a 405?

(Keep in mind that even though John and Amy are forbidden or unauthorized that doesn't mean they arent able to access the same resource with a different HTTP VERB.)

Thanks.

Chris W.
  • 37,583
  • 36
  • 99
  • 136
  • See also http://stackoverflow.com/questions/3297048/403-forbidden-vs-401-unauthorized-http-responses – Ry- Jun 26 '12 at 03:55
  • 1
    So John should get a 401, Amy should get a 403. – Ry- Jun 26 '12 at 03:56
  • 405 Method Not Allowed seems [totally unrelated](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). – Ry- Jun 26 '12 at 03:58
  • @minitech well the thing is *other* methods are still allowed, e.g., GET might be allowed even where DELETE is disallowed. So it seems that one might want to do a 405 to make it clear that the *entire resource* isnt disallowed only this particular VERB associated with it. – Chris W. Jun 26 '12 at 04:11

2 Answers2

43

In this case, I think providing some examples for clarification are useful:

  • Unauthenticated + Supported method = 401
  • Unauthenticated + Unsupported method = 405
  • Authenticated + Authorized + Supported method = 2xx
  • Authenticated + Authorized + Unsupported method = 405
  • Authenticated + Unauthorized + Supported method = 403
  • Authenticated + Unauthorized + Unsupported method = 405

In other words, from a procedural standpoint:

  1. Check whether methods are supported. If not: 405
  2. If supported, check if the user is authenticated. If not: 401
  3. If authenticated, check if the user is authorized. If not: 403
  4. If authorized: 2xx

EDIT: I stumbled upon this diagram and thought it might be useful to anyone else who might stumble across this post. Click to enlarge.

enter image description here

Original here.

docksteaderluke
  • 2,195
  • 5
  • 27
  • 38
  • 7
    Wow, that is incredibly detailed. I pray to the developer gods I will never need to use more than 5% of this flow chart. – Chris W. Nov 15 '16 at 22:53
  • It should be noted that although `401` is actually `401 Unauthorized`, and [this SO thread](https://stackoverflow.com/questions/3297048/403-forbidden-vs-401-unauthorized-http-responses) has some lengthy, undecisive discussions on when should `401` or `403` be used. – OfirD Nov 23 '21 at 19:38
14

405 Method Not Allowed should only be used if you don't support the method. It shouldn't be used to tell the client that they cannot use this method.

So the only good HTTP code in your case would be 401 Unauthorized. It indicates the client that the method exists and that they need to login to access it.

laurent
  • 88,262
  • 77
  • 290
  • 428
  • 6
    Almost. Once you have been authenticated, but are not allowed to do the operation, it'll be 403. – Julian Reschke Jun 26 '12 at 07:40
  • @JulianReschke, hmmm not sure. For 403, the standard states that "Unlike a 401 Unauthorized response, authenticating will make no difference". But in this case, authenticating *would* make a difference since it would allow accessing the resource. – laurent Jun 26 '12 at 08:32
  • 4
    Laurent: "The server understood the request, but refuses to authorize it. Providing different user authentication credentials might be successful, but any credentials that were provided in the request are insufficient. The request SHOULD NOT be repeated with the same credentials." -- http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p2-semantics-latest.html#status.403 – Julian Reschke Jun 26 '12 at 10:26