+So, in all Return-specifications it should be assumed that 'response' is set to
+'ok' on success.
+
+
+Authentication mechanism:
+=========================================================================
+All API nodes except 'auth/login' and 'auth/logout' require a
+'token authentication' based on a session identifier (session) and a
+session authentication key (auth_key) passed as parameters.
+
+The 'session' and 'auth_key' values are provided as response to a
+successful API login through 'auth/login', and must be included as
+parameters to all subsequent calls to the API.
+
+The 'auth_key' has a limited lifetime (configurabel, defaul 5 minutes),
+significantly shorter than the session lifetime. The 'auth_kye' must
+be renewed before the key lifetime expires, by issuing a call to
+'auth/ping'. The ping call will provide a new key that replaces the
+previous 'auth_key' in subsequent calls to the API.
+
+API login may be done using either a username/password combination,
+or using a registered API key tied to the host originating the requests.
+
+See documentation for nodes under 'auth/*' for information about
+adding, removing and maintaining authentication users and keys.
+
+Sample session:
+
+ call auth/login with username and password
+ store session and auth_key for further requests
+
+ perform API calls with session and auth_key set
+ ...
+
+ call auth/ping with session and auth_key set
+ update the auth_key used for requests
+
+ perform API calls with session and auth_key set
+ ...
+
+ call auth/logout with session set
+
+NOTE: that the API also requires COOKIE-support in the user-agent
+used to communicate with the API.
+
+NOTE: See README for information on configuring API authentication
+backends, and boostrapping the user/key authorizations.
+
+Parameter notes:
+=========================================================================
+ 'user'/'alias' parameters marked '*' may alternatively be given as
+ username=foo + domain=bar
+ alias_username=foo + alias_domain=bar
+
+List of API nodes:
+=========================================================================
+
+auth/login
+-------------------
+ Required:
+ username=authuser
+ password=authpassword
+ Alternate:
+ api_key=API_KEY
+
+ Description:
+ TODO: DOCUMENT THIS.
+
+ Return:
+ Returns 'session' set to the allocated session_name and 'auth_key'
+ set to the generated auth_key. These must be used for further access,
+ and the key must be refreshed through 'auth/ping' at intervals.
+ Returns 'failed' with 'cause' = 'unauthorized' if Login failed
+
+auth/logout
+-------------------
+ Required:
+ session=session_name
+
+ Description:
+ TODO: DOCUMENT THIS.
+ // De-authenticate/deauthorize the ongoing session.
+ // I.e. destroy session data, remove session cookies.
+
+ Return:
+ Returns 'ok' on successful logout
+
+auth/ping
+-------------------
+ Required:
+ session=$session_name
+ auth_key=$auth_key
+
+ Description:
+ TODO: DOCUMENT THIS.
+ // API clients are required to periodically ping the server
+ // The time between pings (interval) is 5 minutes?
+ // A ping call refreshes cookie lifetimes, then
+ // generates and stores a new auth_key
+ // The ping required a valid session...
+ // A successful ping returns a 'response' => 'pong'
+ // along with the new auth_key.
+
+ NOTE!: Does not give 'response' => 'ok' !
+
+ Return:
+ Returns 'pong' with 'auth_key' set to the new key to be used
+ with the session_name in further requests.
+
+auth/new_apikey
+-------------------
+ Required:
+ host_ip=10.20.30.40
+ access=limited_read
+
+ Description:
+ TODO: DOCUMENT THIS.
+ 'access' may be one of:
+ * limited_read
+ * full_read
+ * read_write
+
+ Return:
+ Returns 'key', 'host' and 'access'.
+ Returns 'invalid' with 'cause' = 'parameters' on parameter error
+ Returns 'failed' with 'cause' = 'error' on database errors.
+ TODO: Change 'error' to 'dbfail'.
+
+auth/remove_apikey
+-------------------
+ Required:
+ api_key=$key
+
+ Description:
+ TODO: DOCUMENT THIS.
+
+ Return:
+ Returns 'key' set to the removed key on success.
+ Returns 'invalid' on parameter error
+ Returns 'failed' with 'cause' = 'nonexistant' if key does not exist.
+ Returns 'failed' with 'cause' = 'error' on database errors.
+ TODO: Change 'error' to 'dbfail'.
+
+auth/list_apikeys
+-------------------
+
+ Description:
+ TODO: DOCUMENT THIS.
+
+ Return:
+ Returns 'list'
+
+auth/authorize_user
+-------------------
+ Required:
+ username=authuser
+ access=limited_read
+
+ Description:
+ TODO: DOCUMENT THIS.
+ // Add or update a valid back-end user in authorization
+ // if the current authentication has write access.
+ // If the authorization does not exist, add it.
+ // If the user is already authorized, replace access level.
+
+ 'access' may be one of:
+ * limited_read
+ * full_read
+ * read_write
+
+ Return:
+ Returns 'user' and 'access' when user was successfully added.
+ Returns 'invalid' with 'cause' = 'parameters' on parameter error
+ Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
+ Returns 'failed' with 'cause' = 'error' on database errors.
+
+auth/remove_user
+-------------------
+ Required:
+ username=authuser
+
+ Description:
+ TODO: DOCUMENT THIS.
+ // If the current authentication has write access:
+ // Remove authorization for the given users.
+ // Delete user from backend if backend is read-write.
+
+ Return:
+ Returns 'user' when user was successfully removed.
+ Returns 'invalid' with 'cause' = 'parameters' on parameter error
+ Returns 'failed' with 'cause' = 'nonexistant' if user does not exist.
+ Returns 'failed' with 'cause' = 'error' on database errors.
+
+auth/list_users
+-------------------
+
+ Description:
+ Returns 'list'
+
+auth/add_user
+-------------------
+
+ Description:
+ TODO: This is not implemented. Document, write test and implement.
+ Returns 'notimplemented'
+ // Add user to backend if backend is read-write and
+ // the current authentication has write access.
+ // The created user should be added to authorizations
+ // with an access level of "limited_read (1)"
+
+auth/update_user
+-------------------
+
+ Description:
+ TODO: This is not implemented. Document, write test and implement.
+ Returns 'notimplemented'
+ // Update the given user in the backend, if the backend
+ // is read-write, and the current authentication has
+ // write access.
+
+user/get
+-------------------
+ Required:
+ user=user@bar.bz *
+
+ Description: