[feature] require authentication token for api

implements a global auth token for the app.

this token is written to .config/leap/authtoken, and passed to the
anchor part of the landing URI when opening the index resource by the
browser.

- Resolves: #8765

1 files changed, 25 insertions, 2 deletions

diff --git a/docs/core/index.rst b/docs/core/index.rst
index d03dd727..c7fb1780 100644
--- a/docs/core/index.rst
+++ b/docs/core/index.rst
@@ -24,8 +24,31 @@ throught a REST API. In bitmaskd.cfg::
   [services]
   web = True
 
-API Authentication
-==================
+
+Global API Authentication
+=========================
+
+To avoid some kind of attacks, the Bitmask API is protected by a global
+authentication token.
+
+The JS API receives this value when the initial entrypoint is loaded for the
+first time, in the anchor part of the url.
+
+To authenticate any request to the API, the ``X-Bitmask-Auth`` header has to be
+added to it, set to the single value that is initialized during the bitmask
+deaemon startup::
+
+  curl -X POST http://localhost:7070/API/mail/status
+  unauthorized:bad auth token
+
+  curl -X POST http://localhost:7070/API/mail/status -H 'X-Bitmask-Auth: fae20706aa4f4f98ac0e67996787a370'
+  {"result": {"status": "on", "childrenStatus": {"smtp": {"status": "on", "error": null}, "imap": {"status": "on", "error": null}}, "error": null}, "error": null}
+
+This token can be found in ``.config/leap/authtoken``
+
+
+API Authentication (this section not implemented yet)
+======================================================
 
 By default, the resources in the API are protected by an authentication token.