From e3999c4906348dadcc85eec1df9a48e776deccd5 Mon Sep 17 00:00:00 2001
From: "Kali Kaneko (leap communications)" <kali@leap.se>
Date: Thu, 23 Feb 2017 00:35:33 +0100
Subject: [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
---
 docs/core/index.rst | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

(limited to 'docs/core')

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.
 
-- 
cgit v1.2.3