.. _non-interactive-login:

Non-interactive Login
---------------------


.. _12.5(1)|VOSS-346:
.. _18.1-Patch-Bundle-3|VOSS-346:



The following request, parameter and endpoint is available on the API: 

**REQUEST**:

  ::

     POST <hostname>/noninteractivelogin/


**PAYLOAD**:

* ``Content-Type: application/json``
* JSON containing user credentials, for example:

  ::
  
     {
      "username":"joebloggs@email.com",
      "password":"mysecret"
     }

**PARAMETER**:

A request parameter to expose hierarchy and role related data is available: ``rbacinfo``



With the user credentials payload as above,
the following calls result in the same response:

::

   POST <hostname>/noninteractivelogin/
   POST <hostname>/noninteractivelogin/?rbacinfo=false
   POST <hostname>/noninteractivelogin/?rbacinfo=False


If the request is successful:

* the HTTP response is 200
* the JSON body is for example: 
  

::

     {
      "is_externally_authenticated": false,
      "last_successful_login_time": "2017-06-12T13:28:55.785Z",
      "num_of_failed_login_attempts": 0
     }

  
**X-CSRFToken VALUE**

When enabling the ``rbacinfo`` parameter and
with the same user credentials payload as above,
the following calls result in the same response:

::

   POST <hostname>/noninteractivelogin/?rbacinfo
   POST <hostname>/noninteractivelogin/?rbacinfo=true
   POST <hostname>/noninteractivelogin/?rbacinfo=True
   POST <hostname>/noninteractivelogin/?rbacinfo=


If the request is successful:

* the HTTP response is 200
* the JSON body is for example: 
  

::

   {
    "hierarchy_path": "sys.Prov",
    "language": "en-us",
    "is_externally_authenticated": false,
    "hierarchy_name": "Prov",
    "hierarchy_href": "/api/data/HierarchyNode/593e8fa28719cf00060a7011/",
    "role_name": "ProvRole",
    "role_href": "/api/data/Role/593e91098719cf00060a7029/",
    "role_pkid": "593e91098719cf00060a7029",
    "last_successful_login_time": "2017-06-12T13:28:38.390Z",
    "hierarchy_type": "TestHierarchyNodeType",
    "hierarchy_pkid": "593e8fa28719cf00060a7011",
    "num_of_failed_login_attempts": 0
   }


If a ``data/PrivacyPolicy`` instance is found at or above the logged
in user's hierarchy, the data for the instance closest to that hierarchy
will be included in the response JSON body:

::

   {
    "privacy_policy": {
        "url": "<URL from data/PrivacyPolicy>",
        "name": "<Name from data/PrivacyPolicy>"
    },
    "hierarchy_path": "sys.Prov",
    "language": "en-us",
    ...


.. note::

   * Upon the first successful login, the ``last_successful_login_time``
     is an empty string. 
   * Upon a subsequent successful login, the 
     ``last_successful_login_time`` is the login time *prior* to
     current session. 
   * The ``num_of_failed_login_attempts`` value
     is reset to 0 after a successful login.


If the requests above fail:

* the HTTP response is 403
* the JSON body is: 
  
    ::
  
      {
       "error_message": "Please enter a valid username and password.",
       "error_code": 27009
      }
  
* the X-CSRFToken value


.. |VOSS-4-UC| replace:: VOSS-4-UC
.. |Unified CM| replace:: Unified CM