Give authorization API dedicated section and document common problems

cc @tclem