Take the 2-minute tour ×

What does RESTful Authentication mean and how does it work? I can't find a good overview on google. My only understanding is that you pass the session key (remeberal) in the URL, but this could be horribly wrong.

share|improve this question
When I google Restful Authentication I find a dozen RoR plugins. I'm assuming those are NOT what you're looking for. If not RoR, then what language? What web server? –  S.Lott Nov 26 '08 at 2:21
It won't be horribly wrong if you use HTTPS. The complete HTTP request along with the URL would be encrypted. –  Bharat Khatri Jul 24 '13 at 14:08
@BharatKhatri: Yes it would. I would never pass sensitive information in the URL visible to the user. This information is much more likely to leak for practical purposes. HTTPS can't help for accidental leakage. –  Jo So Sep 12 '13 at 9:25
add comment

12 Answers

up vote 149 down vote accepted



  • HTTP basic auth over HTTPS;
  • Cookies and session management;
  • Query Authentication with additional signature parameters.

You'll have to adapt, or even better mix those techniques, to match your software architecture at best.


HTTP basic auth over HTTPS

This first solution, based on the standard HTTPS protocol, is used by most web services.

It's easy to implement, available by default on all browsers, but has some known draw-backs, like the awful authentication window displayed on the Browser, which will persist (there is no LogOut-like feature here), some server-side additional CPU consumption, and the fact that the user-name and password are transmitted (over HTTPS) into the Server (it should be more secure to let the password stay only on the client side, during keyboard entry, and be stored as secure hash on the Server).

Session via Cookies

To be honest, a session managed on the Server is not truly Stateless.

One possibility could be to maintain all data within the cookie content. And, by design, the cookie is handled on the Server side (Client in fact does even not try to interpret this cookie data: it just hands it back to the server on each successive request). But this cookie data is application state data, so the client should manage it, not the server, in a pure Stateless world.

The cookie technique itself is HTTP-linked, so it's not truly RESTful, which should be protocol-independent, IMHO.

Query Authentication

Query Authentication consists in signing each RESTful request via some additional parameters on the URI. See this reference article.

It was defined as such in this article:

All REST queries must be authenticated by signing the query parameters sorted in lower-case, alphabetical order using the private credential as the signing token. Signing should occur before URL encoding the query string.

This technique is perhaps the more compatible with a Stateless architecture, and can also be implemented with a light session management (using in-memory sessions instead of DB persistence).

Server-side data caching can be always available. For instance, in our framework, we cache the responses at the SQL level, not at the URI level. So adding this extra parameter doesn't break the cache mechanism.

It's worth concluding that REST is not only HTTP-based, even if, in practice, it's mostly implemented over HTTP. REST can use other communication layers. So a RESTful authentication is not just a synonym of HTTP authentication, whatever Google answers. It should even not use the HTTP mechanism at all, but shall be abstracted from the communication layer.

See this article for some details about RESTful authentication in a client-server ORM, based on JSON and REST. Since we allow communication not only over HTTP/1.1, but also named pipes or GDI messages (locally), we tried to implement a truly RESTful authentication pattern, and not rely on HTTP specificity (like header or cookies).

share|improve this answer
If you use Cookie as a better replacement for HTTP Basic Auth you can do truly stateless authentication with a method for expiring the authentication and ability to logout. An example implementation could use cookie called Emulated-HTTP-Basic-Auth with similar value to real HTTP Basic Auth and in addition set expire time. Log out can then be implemented with removing that cookie. I'd guess that any client able to support HTTP Basic Auth can also support cookie authentication done this way. –  Mikko Rantalainen Apr 23 '13 at 7:40
@MikkoRantalainen But this cookie will still be managed by the server, as I wrote. It is some kind of stateless, but not "pure" stateless. In all cases, you need JavaScript code dedicated to client login/logout, which is perfectly possible e.g. with HTTP Digest Auth - good idea, but no big benefit, here, to reinvent the wheel. –  Arnaud Bouchez May 3 '13 at 5:15
I would claim that server implements the UI and logic for configuring the header but the header itself is stateless. A client designed for the API could skip using server help for configuring the header and just pass the required information similar to HTTP Basic Auth. My point is that common UAs (browsers) have such a poor implementation of Basic Auth that it cannot be used. A server provided emulation for the same stuff in another header (Cookie) can be used instead. –  Mikko Rantalainen May 3 '13 at 11:00
Of course, the server could support accepting both HTTP Basic Auth and Cookie. However, try to never request HTTP Basic Auth from a browser to avoid the bad UI. –  Mikko Rantalainen May 3 '13 at 11:01
I guess the correct answer is stackoverflow.com/questions/6068113/… –  graffic Jun 25 '13 at 10:33
show 4 more comments

I really doubt whether the people enthousiastically shouting "HTTP Authentication" ever tried making a browser-based application (instead of a machine-to-machine web service) with REST. (no offense intended - I just don't think they ever faced the complications)

Problems I found with using HTTP Authentication on RESTful services that produce HTML pages to be viewed in a browser are:

  • user typically gets an ugly browser-made login box, which is very user-unfriendly. you cannot add password retrieval, help boxes, etcetera.
  • logging out or logging in under a different name is a problem - browsers will keep sending authentication information to the site until you close the window
  • timeouts are difficult

A very insightful article that tackles these point by point is here, but this results to a lot of browser-specific javascript hackery, workarounds to workarounds, et cetera. As such, it is also not forward-compatible so will require constant maintenance as new browsers are released. I do not consider that clean and clear design, plus I feel it is a lot of extra work and headache just so that I can enthusiastically show my REST-badge to my friends.

I believe cookies are the solution. But wait, cookies are evil, aren't they? No they're not, the way cookies are used often is evil. A cookie itself is just a piece of client-side information, just like the HTTP authentication info that the browser would keep track of while you browse. And this piece of client-side information is sent to the server at every request, again just like the HTTP Authentication info would be. Conceptually, the only difference is that the content of this piece of client-side state can be determined by the server as part of its response.

By making sessions a RESTful resource with just the following rules:

  • A session maps a key to a user id (and possibly a last-action-timestamp for timeouts)
  • If a session exists, then that means that the key is valid.
  • Login means POSTing to /sessions, a new key is set as a cookie
  • Logout means DELETEing /sessions/{key} (with overloaded POST, remember, we're a browser and HTML 5 is a long way to go yet)
  • Authentication is done by sending the key as a cookie at every request and checking whether the session exists and is valid

The only difference to HTTP Authentication, now, is that the authentication key is generated by the server and sent to the client who keeps sending it back, instead of the client computing it from the entered credentials.

converter42 adds that when using https (which we should), it is important that the cookie will have its secure flag set, so that authentication info is never sent over a non-secure connection. Great point, hadn't seen it myself.

I feel that this is a sufficient solution that works fine, but I must admit that I'm not enough of a security expert to identify potential holes in this scheme - all I know is that hundreds of non-RESTful web applications use essentially the same login protocol ($_SESSION inphp, HttpSession in Java EE, etc). The cookie header contents is simply used to address a server-side resource, just like an accept-language might be used to access translation resources, etcetera. I feel that it is the same, but maybe others don't? What do you think, guys?

share|improve this answer
This is fine as long as you set the secure flag on the cookie so the client will never transmit it to the server over a non-secure connection. –  converter42 Mar 3 '11 at 17:07
This is a pragmatic answer and the proposed solution works. However, using terms "RESTful" and "session" in the same sentence is just wrong (unless there is also "not" in between ;). In other words: any web service that uses sessions is NOT RESTful (by definition). Don't get me wrong - you can still use this solution (YMMV), but the term "RESTful" can't be used for it. I recommend the O'Reilly book on REST which is very readable and explains the subject in depth. –  johndodo Jul 29 '11 at 6:38
@skrebbel: pure REST solution would send authentication data each time it requests a resource, which is less than perfect (HTTP Auth does this). Proposed solution works and is better for most use cases, but it is not RESTful. No need for war, I use this solution too. I just don't claim it is RESTful. :) –  johndodo Aug 3 '11 at 14:11
Oh come on, give an example then. What's that other way, that works well? I'd genuinely like to know. HTTP Auth surely isn't, you can't logout without closing the browser and you can't offer decent login UX without lots of browser-specific non-future-compatible JS. I don't care that much about "purely RESTful" vs "almost RESTful" and the whole associated religious debate, but if you say there are several ways, you should spell them out. –  skrebbel Aug 24 '11 at 15:47
A truly RESTful authentication with real world user agents (a.k.a. "browsers") consists of a cookie containing the value of HTTP Authentication. This way the server can provide the UI for entering login and password and the server can force the logout (by deleting the cookie). In addition, instead of responding 401 to require login when authentication is failed, the server must use temporary redirect to login screen and after successful login use temporary redirect back to previous location. Plus the server must embed logout action (POST form) to pretty much every page for logged in users. –  Mikko Rantalainen Feb 7 '12 at 12:15
show 9 more comments

It's certainly not about "session keys" as it is generally used to refer to sessionless authentication which is performed within all of the constraints of REST. Each request is self-describing, carrying enough information to authorize the request on its own without any server-side application state.

The easiest way to approach this is by starting with HTTP's built-in authentication mechanisms in RFC 2617.

share|improve this answer
add comment

First and foremost, a RESTful web service is STATELESS (or in other words, SESSIONLESS). Therefore, a RESTful service does not have and should not have a concept of session or cookies involved. The way to do authentication or authorization in the RESTful service is by using the HTTP Authorization header as defined in the RFC 2616 HTTP specifications. Every single request should contain the HTTP Authorization header, and the request should be sent over an HTTPs (SSL) connection. This is the correct way to do authentication and to verify the authorization of requests in a HTTP RESTful web services. I have implemented a RESTful web service for the Cisco PRIME Performance Manager application at Cisco Systems. And as part of that web service, I have implemented authentication/authorization as well.

Rubens Gomes.

share|improve this answer
HTTP authentication still requires the server to keep track of user ids and passwords. This is not completely stateless. –  jcoffland Feb 3 at 23:44
It is stateless in the sense that each request is valid on its own without any requirements of previous requests. How this is implemented on the server is another matter, if authentication is expensive you could do some caching and re-authenticate on cache miss. Very few servers are completely stateless where the output is purely a function of the input. It is usually a query of or an update to some state. –  Erik Martino Feb 13 at 13:43
add comment

The 'very insightful' article mentioned by @skrebel ( http://www.berenddeboer.net/rest/authentication.html ) discusses a convoluted but really broken method of authentication.

You may try to visit the page (which is supposed to be viewable only to authenticated user) http://www.berenddeboer.net/rest/site/authenticated.html without any login credentials.

(Sorry I can't comment on the answer.)

I would say REST and authentication simply do not mix. REST means stateless but 'authenticated' is a state. You cannot have them both at the same layer. If you are a RESTful advocate and frown upon states, then you have to go with HTTPS (i.e. leave the security issue to another layer).

share|improve this answer
add comment

Enough already is said on this topic by good folks here. But here is my 2 cents.

There are 2 modes of interaction:

  1. human-to-machine (HTM)
  2. machine-to-machine (MTM)

The machine being the common denominator, expressed as the REST APIs, and the actors/clients being either the humans or the machines.

Now, in a truly RESTful architecture, the concept of statelessness implies that all relevant application states (meaning the client side states) must be supplied with each and every request. By relevant, it is meant that whatever is required by the REST API to process the request and serve an appropriate response.

When we consider this in the context of human-to-machine applications, "browser based" as Skrebbel points out above, this means that the (web) application running in the browser will need to send its state and relevant information with each request it makes to the back end REST APIs.

Consider this: You have a data/information platform exposed as set of REST APIs. Perhaps you have a self-service BI platform that handles all the data cubes. But you want your (human) customers to access this via (1) web app, (2) mobile app, and (3) some 3rd party application. In the end, even chain of MTMs lead upto HTM - right. So human users remain at the apex of information chain.

In the first 2 cases, you have a case for human-to-machine interaction, the information being actually consumed by a human user. In the last case, you have a machine program consuming the REST APIs.

The concept of authentication applies across the board. How will you design this so that your REST APIs are accessed in a uniform, secured manner? The way I see this, there are 2 ways:


  1. There is no login to begin with. Every request performs the login
  2. The client sends its identifying parameters + the request specific parameters with each request
  3. The REST API takes them, turns around, pings the user store (whatever that is) and confirms the auth
  4. If the auth is established, services the request; otherwise, denies with appropriate HTTP status code
  5. Repeat the above for every request across all the REST APIs in your catalog


  1. The client begins with an auth request
  2. A login REST API will handle all such requests
  3. It takes in auth parameters (API key, uid/pwd or whatever you choose) and verifies auth against the user store (LDAP, AD, or MySQL DB etc.)
  4. If verified, creates an auth token and hands it back to the client/caller
  5. The caller then sends this auth token + request specific params with every subsequent request to other business REST APIs, until logged out or until the lease expires

Clearly, in Way-2, the REST APIs will need a way to recognize and trust the token as valid. The Login API performed the auth verification, and therefore that "valet key" needs to be trusted by other REST APIs in your catalog.

This of course means that the auth key/token will need to be stored and shared among the REST APIs. This shared, trusted token repository can be local/federated whatever, allowing REST APIs from other organizations to trust each other.

But I digress.

The point is, a "state" (about the client's authenticated status) needs to be maintained and shared so that all REST APIs can create a circle of trust. If we do not do this, which is the Way-1, we must accept that an act of authentication must be performed for any/all requests coming in.

Performing authentication is a resource intensive process. Imagine executing SQL queries, for every incoming request, against your user store to check for uid/pwd match. Or, to encrypt and perform hash matches (the AWS style). And architecturally, every REST API will need to perform this, I suspect, using a common back end login service. Because, if you dont, then you litter the auth code everywhere. A big mess.

So more the layers, more latency.

Now, take Way-1 and apply to HTM. Does your (human) user really care if you have to send uid/pwd/hash or whatever with every request? No, as long as you don't bother her by throwing the auth/login page every second. Good luck having customers if you do. So, what you will do is to store the login information somewhere on the client side, in browser, right at the beginning, and send it with every requests made. For the (human) user, she has already logged in, and a "session" is available. But in reality, she is authenticated on every request.

Same with Way-2. Your (human) user will never notice. So no harm done.

What if we apply Way-1 to MTM? In this case, since its a machine, we can bore the hell out of this guy by asking it submit authentication information with every request. Nobody cares! Performing Way-2 on MTM will not evoke any special reaction; its a damn machine. It could care less!

So really, the question is what suits your need. Statelessness has a price to pay. Pay the price and move on. If you want to be a purist, then pay the price for that too, and move on.

In the end, philosophies do not matter. What really matter is information discovery, presentation, and the consumption experience. If people love your APIs, you did your job.

share|improve this answer
add comment

I think restful authentication involves the passing of an authentication token as a parameter in the request. Examples are the use of apikeys by api's. I don't believe the use of cookies or http auth qualifies.

share|improve this answer
add comment

To be honest with you I've seen great answers here but something that bothers me a bit is when someone will take the whole Stateless concept to a extreme where it becomes dogmatic. It reminds me of those old Smalltalk fans that only wanted to embrace pure OO and if something is not an object, then you're doing it wrong. Give me a break.

The RESTful approach is supposed to make your life easier and reduce the overhead and cost of sessions, try to follow it as it is a wise thing to do, but the minute you follow a discipline (any discipline/guideline) to the extreme where it no longer provides the benefit it was intended for, then you're doing it wrong. Some of the best languages today have both, functional programming and object orientation.

If the easiest way for you to solve your problem is to store the authentication key in a cookie and send it on HTTP header, then do it, just don't abuse it. Remember that sessions are bad when they become heavy and big, if all your session consists of is a short string containing a key, then what's the big deal?

I am open to accept corrections in comments but I just don't see the point (so far) in making our lives miserable to simply avoid keeping a big dictionary of hashes in our server.

share|improve this answer
People are not trying to forbid you from using sessions. You are free to do it. But if you do, it is not REST. –  André Caldas Dec 19 '13 at 0:28
@AndréCaldas it is not REST in the same way that having functions or primitive types in a language is not oop. I'm not saying having sessions is advisable. I'm just giving my opinion regarding following a set of practices to an extent they no longer provide someone with benefits. (Btw, notice I didn't oppose your remarks, however, I wouldn't say it's not REST, I'd say it's not pure REST). –  arg20 Dec 22 '13 at 17:53
--- agreed! :-) –  André Caldas Dec 23 '13 at 0:47
So what do we call it if it's not RESTful? And surely if a request includes the session Id, then that's as stateless as a request including a user Id? Why are user Id's stateless and session Id's stateful? –  mfhholmes Dec 24 '13 at 15:05
add comment

Here is a truly and completely RESTful authentication solution:

  1. Create a public/private key pair on the authentication server.
  2. Distribute the public key to all servers.
  3. When a client authenticates:

    3.1. issue a token which contains the following:

    • Expiration time
    • users name (optional)
    • users IP (optional)
    • hash of a password (optional)

    3.2. Encrypt the token with the private key.

    3.3. Send the encrypted token back to the user.

  4. When the user accesses any API they must also pass in their auth token.

  5. Servers can verify that the token is valid by decrypting it using the auth server's public key.

This is stateless/RESTful authentication.

Note, that if a password hash were included the user would also send the unencrypted password along with the authentication token. The server could verify that the password matched the password that was used to create the authentication token by comparing hashes. A secure connection using something like HTTPS would be necessary. Javascript on the client side could handle getting the user's password and storing it client side, either in memory or in a cookie, possibly encrypted with the server's public key.

share|improve this answer
What if someone gets hold of that auth token and invoke APIs with it pretending to be client? –  Abidi Oct 23 '13 at 10:22
@Abidi, yes that's a problem. You could require a password. A hash of the password could be included in the authentication token. If someone was able to steal the token it would be vulnerable to offline brute force attacks. If a strong passphrase were chosen that would not be a problem. Note, that if you used https token theft would require the attacker to first gain access to the client's machine. –  jcoffland Feb 3 at 23:30
add comment

That's the way to do that: Using OAuth 2.0 for Login.

You may use other authentication methods other then Google's as long as it supports OAuth.

share|improve this answer
add comment

To answer this question from my understanding...

An authentication system that uses REST so that you do not need to actually track or manage the users in your system. This is done by using the HTTP methods POST, GET, PUT, DELETE. We take these 4 methods and think of them in terms of database interaction as CREATE, READ, UPDATE, DELETE (but on the web we use POST and GET because that is what anchor tags support currently). So treating POST and GET as our CREATE/READ/UPDATE/DELETE (CRUD) then we can design routes in our web application that will be able to deduce what action of CRUD we are achieving.

For example, in a Ruby on Rails application we can build our web app such that if a user who is logged in visits http://store.com/account/logout then the GET of that page can viewed as the user attempting to logout. In our rails controller we would build an action in that logs the user out and sends them back to the home page.

A GET on the login page would yield a form. a POST on the login page would be viewed as a login attempt and take the POST data and use it to login.

To me, it is a practice of using HTTP methods mapped to their database meaning and then building an authentication system with that in mind you do not need to pass around any session id's or track sessions.

I'm still learning -- if you find anything I have said to be wrong please correct me, and if you learn more post it back here. Thanks.

share|improve this answer
add comment

Using a Public key infrastruction in which the registration of a key involves proper binding ensures that the public key is bound to the individual to which it is assigned in a way that ensures non-repudiation

See http://en.wikipedia.org/wiki/Public_key_infrastructure . If you follow the proper PKI standards, the person or agent who improperly uses the stolen key can be identified and locked out. If the agent is required to use a certificate, the binding gets pretty tight. A clever and quick-moving thief can escape, but they leave more crumbs.

share|improve this answer
add comment

Your Answer


