Add documentation on use API keys

[struan]

Also remove docs on how to use username and passwords as that's going to be going away

[chrismytton]

Needs a small rebase onto latest gh-pages, but otherwise look good. :+1: