Refactoring authentication in the api

* drop custom headers
* send proper header so browsers can respond to it
* extend documentation
* extend spec

Squashed commit of the following:

commit d3e048971c9b4b5a9250f4aa1308e280096f03d2
Author: Thomas Schank <DrTom@schank.ch>
Date:   Tue Mar 25 11:25:46 2014 +0100

    Added ref to test

commit 8349a95f29555bf3f6c9e0f897e230105709c1eb
Author: Thomas Schank <DrTom@schank.ch>
Date:   Tue Mar 25 10:56:30 2014 +0100

    Extending spec

commit 8e7ef002f4f67b14a1ddabe8f1d10dd45bf97295
Author: Thomas Schank <DrTom@schank.ch>
Date:   Tue Mar 25 10:40:55 2014 +0100

    Refactoring authorization