.. auth.rst
   Copyright (c) 2016-2017 LMG. All rights reserved
   This software is the confidential and proprietary information of LMG ("Confidential Information").
   You must not disclose such Confidential Information.
   Created by usischev on 10.05.2017

Authentication & Authorization
------------------------------

.. rubric:: API Endpoints

.. toctree::
   :maxdepth: 2

   auth-login
   auth-recovery
   auth-signup

.. _user-sessions-label:

User Sessions
^^^^^^^^^^^^^

User session is identified with session token, which needs to be supplied by the client in ``Authorization`` header::

    Authorization: Bearer <session_token>

To authorize user with the API service, client must use authentication endpoints. Upon successful authentication,
session token is returned in the ``session_token`` field. Response also includes ``session_state`` field identifying
current session authorization state. Session state code can be one of the following strings:

**authorized**
   User is successfully authenticated and authorized. Client can make regular API requests using received session token.

**checkpassword**
   To authorize user, client application must provide user password to ``auth/checkpassword`` endpoint using the
   received temporary session token. Upon successful validation, a new session token is returned
   with ``authorized``, ``checkotp``, or ``setpassword`` session state. The new token must be used for further requests.

**checkotp**
   To authorize user, client application must provide One-Time Password to ``auth/checkotp`` endpoint using the
   received temporary session token. Upon successful validation, a new session token is returned
   with ``authorized`` or ``setpassword`` session state. The new token must be used for further requests.

**setpassword**
   User is successfully authenticated and required to set a new password using ``auth/setpassword`` endpoint with the
   received temporary session token. When new password is successfully set, a new session token is returned with
   ``authorized`` session state. The new token must be used for further requests.

**recovery-checkotp**
   To recover access with phone method, client application must provide One-Time Password to ``auth/recovery/checkotp``
   endpoint using the received temporary session token. Upon successful validation, a new session token is returned
   with ``recovery-setpassword`` session state. The new token must be used for further requests.

**recovery-checkquestion**
   To recover access with control question method, client application must provide control answer to
   ``auth/recovery/checkquestion`` endpoint using the received temporary session token. Upon successful validation, a
   new session token is returned with ``recovery-setpassword`` session state. The new token must be used for further
   requests.

**recovery-setpassword**
   User is authenticated for access recovery and required to set a new password using ``auth/setpassword`` endpoint
   with the received temporary session token. When new password is successfully set, client application should start
   regular authentication process with ``auth/login`` endpoint.

**acceptdisclaimers**
   User is successfully authenticated and required to accept legal disclaimers using ``auth/acceptdisclaimers`` endpoint
   with the received temporary session token. When disclaimers are accepted, a new session token is returned with
   ``authorized`` session state. The new token must be used for further requests.

.. rubric:: Session Tokens

JSON Web Tokens (JWT) format with JWS Compact Serialization is used for session tokens. Client applications never
generate these tokens but can use session information encoded in fields (claims) of a session token. Data fields can
be obtained from JWT like this:

#. JWT consists of three parts delimited by dots (``.``), the second (middle) part should be extracted for payload

#. Payload text must be decoded using Base64url encoding

#. Decoded payload text is valid JSON that can be parsed with standard tools

Payload for session tokens has these fields useful for client applications:

**exp** (integer)
   Session expiration time as POSIX timestamp. If an expired token is supplied to an API endpoint requiring
   authorization, ``auth.token.expired`` error code will be returned with HTTP 401 status.

**session_state** (string)
   Session state code, as described earlier. If an endpoint requires a different session state,
   ``auth.session.invalid`` error code will be returned with HTTP 401 status.