[docs] fix typos

2 files changed, 48 insertions, 31 deletions

diff --git a/docs/core/index.rst b/docs/core/index.rst
index b17a4320..84ac8fb4 100644
--- a/docs/core/index.rst
+++ b/docs/core/index.rst
@@ -12,11 +12,11 @@ The bitmask core daemon can be launched like this::
 
   bitmaskd
 
-The command-line program ``bitmaskctl`` and the GUI, will launch the
+The command-line program ``bitmaskctl`` and the GUI will launch the
 daemon when needed.
 
-Starting the API server
-=======================
+Starting the REST service
+=========================
 
 If configured to do so, the bitmask core will expose all of the commands
 throught a REST API. In bitmaskd.cfg::
@@ -24,6 +24,45 @@ throught a REST API. In bitmaskd.cfg::
   [services]
   web = True
 
+API Authentication
+==================
+
+By default, the resources in the API are protected by an authentication token.
+
+The rationale is that, since the Bitmask core can be used simultaneously by
+several users, no single user should be able to interfere with others by
+querying for sensible information or disrupting other users' interaction with
+running services.
+
+Therefore, there's a small white list of resources that do not
+need authentication, based on which is the subset of the API that needs to
+provide functionality for the creation of new accounts (the first-run wizard
+from the UI perspective).
+
+The local authentication token is sent back in the response for an
+authentication call.
+
+This local session token is different from the remote SRP token, although both
+are returned together. In the case that the remote SRP authentication with the
+provider fails (or with no network connectivity), the backend **should** signal
+the error but equally return a local authentication token (this is not
+implemented yet, but needs to be done to support an offline mode of operation).
+
+To authenticate any request to the API, the ``Authentication`` header has to be
+added to it. You need to pass a ``Token`` field, with a value equal to the
+concatenation of the username and the local session token , base64-encoded::
+
+
+   $ curl -X POST localhost:7070/API/core/stop
+   $ Unauthorized
+
+   >>> import base64                                                                                           
+   >>> base64.b64encode('user@provider.org:52dac27fcf633b1dba58')
+   'dXNlckBwcm92aWRlci5vcmc6NTJkYWMyN2ZjZjYzM2IxZGJhNTg='
+
+   $ curl -X POST localhost:7070/API/core/stop -H 'Authentication: Token dXNlckBwcm92aWRlci5vcmc6NTJkYWMyN2ZjZjYzM2IxZGJhNTg='
+   $ {'shutdown': 'ok'}
+
 
 Resources
 ========= 
@@ -252,7 +291,7 @@ JSON-encoded data to the POST.
         * ``invitecode`` *(optional)* - an optional invitecode, to be used if
           the provider requires it for creating a new account.
         * ``autoconf`` *(optional)* - whether to autoconfigure the provider, if
-          we don't have seen it before.
+          we have not seen it before.
 
   **Status codes**:
         * ``200`` - no error
@@ -332,23 +371,3 @@ JSON-encoded data to the POST.
   Export keys for an user.
 
 
-API Authentication
-==================
-
-Most of the resources in the API are protected by an authentication token.
-To authenticate the request, the ``Authentication`` header has to be added to
-it. You need to pass a ``Token`` field, with a value equal to the concatenation of
-the username and the local session token that you have received after the
-authentication call, base64-encoded::
-
-
-   $ curl -X POST localhost:7070/API/core/stop
-   $ Unauthorized
-
-   >>> import base64                                                                                           
-   >>> base64.b64encode('user@provider.org:52dac27fcf633b1dba58')
-   'dXNlckBwcm92aWRlci5vcmc6NTJkYWMyN2ZjZjYzM2IxZGJhNTg='
-
-   $ curl -X POST localhost:7070/API/core/stop -H 'Authentication: Token dXNlckBwcm92aWRlci5vcmc6NTJkYWMyN2ZjZjYzM2IxZGJhNTg='
-   $ {'shutdown': 'ok'}
-
diff --git a/src/leap/bitmask/core/_session.py b/src/leap/bitmask/core/_session.py
index 24070a82..9b22f154 100644
--- a/src/leap/bitmask/core/_session.py
+++ b/src/leap/bitmask/core/_session.py
@@ -33,15 +33,15 @@ logger = Logger()
 class SessionService(HookableService):
 
     """
-    This service holds random local-session tokens, that will be use to protect
-    the access to the API resources.
+    This service holds random local-session tokens, that will be used to
+    protect the access to the API resources.
 
     These tokens are different from the (remote) SRP session tokens: the
-    local-session tokens are ephimeral and generated by the local Bitmask
-    deamon.
+    local-session tokens are also ephemeral, but generated by the local Bitmask
+    daemon.
 
     Right now, they are generated when a soledad instance is successfully
-    created.  This might be subject to further discussion, but this is the
+    created. This might be subject to further discussion, but this is the
     earliest moment in which we can decide if a user should be authenticated
     locally: it means that the entered password is able to decrypt the local
     store. In this way, we can protect the API resources even in the case that
@@ -65,6 +65,4 @@ class SessionService(HookableService):
     def hook_on_new_soledad_instance(self, **kw):
         user = kw['user']
         session_token = binascii.hexlify(os.urandom(10))
-        print '---------------------------------------------------'
-        print "hook on new soledad instance!", user, session_token
         self._tokens[user] = session_token