Ahoy-hoy, Sorry for the looooong delay but some things must to be tested before we assume that this "just works" in a straight and plain document. I'll upload this document at our aerogear site, but here comes to be reviewed in a temporary location: http://aerogear.abstractj.org/docs/SecurityApi.html Some topics were left with _todo_, because I would like to hear your opinion before move on. Tons of details we'll just find out during the implementation, but before we invest our time with broken RESTful contracts, let's discuss it before. Do you want to tweak this document? - https://github.com/aerogear/beta.aerogear.org/blob/master/docs/reference/... Is there something missing? Let me know. New features have emerged during this documentation process like: https://issues.jboss.org/browse/AEROGEAR-431 https://issues.jboss.org/browse/AEROGEAR-433 -- abstractj JBoss, a division of Red Hat