I'm working through an API design where a user's authentication will be verified by the presence of a valid forms authentication ticket in a session cookie. However, there are additional levels of access that can exist for particular resource URLs. When attempting to access those, it seems like returning a 401 would be the most appropriate response.

However, generally we handle 401s by redirecting to a sign-in page. That would not be a valid course of action for clients on certain resources, where there's an additional step required (e.g., email validation, signing up for a particular role).

Is there a standard way to communicate where to go next when responding with a 401? I'm tempted to include something in the Location header, but that seems only appropriate for 302s after a POST. I'm also reluctant to use URLs to specify where to go, since clients may not be restricted to browsers.

Any good examples or standards docs I can refer to on this?

  • thinking out loud: multipart/alternative with text/html and application/something – hildred Dec 3 '13 at 18:49

I don't see anything in the RFC-2616 Location header definition that limits it's use to 3xx or 201 HTTP status responses. I agree the 401 response would be appropriate since the HTTP 403 status response implies there is no recourse even when subsequent authentication is possible. What you're suggesting is an application specific variation on the established HTTP Basic authentication protocol.

This StackOverflow answer to a similar question gives an example which includes the location as part of the required WWW-Authenticate header contents in a 401 response instead of in the separate Location header. I believe either approach respects the RFC-2616 & RFC-2617 specs but I'd would choose embedding the location in the WWW-Authenticate header contents due to its simplicity of implementation since it keeps all the application specific authentication information in a single place.


I've always considered redirects to be part of the convenience for the UI or UI agent. Whereas REST API is more like a normal function API intended for clients that were coded specifically to communicate with it.

Just like many OS functions might fail with "access denied" and not redirect you to an authentication resource, I wouldn't expect REST API to redirect me either. If someone codes the client to talk to your REST server, that client should also be coded to perform proper authentication in the first place.

So my take would be to reply with 401, or maybe even 403 Forbidden to distinguish between clients that are not authenticated vs. those that are authenticated but do not have correct permissions. And possibly include human-readable text string indicating the reason for authentication/authorization failure, but don't worry about any redirects.

Your Answer

