Upgrade authentication docs to make them more complete, accessible.

* document how it's intended to be used-- as a mix-in
* documennt side-effects-- it sets some properties on the calling
* document what args are passed to the callback called.
* Link to related REST API documentation
Merge pull request #64 from markstos/improve-authentication-docs

Upgrade authentication docs to make them more complete, accessible.