Atheneum/server/documentation/api/authentication.rst

Authentication API
==================

.. http:post:: /auth/login

   Authenticate with the server and receive a userToken for requests.

   **Example request**:

   .. sourcecode:: http

      POST /auth/login HTTP/1.1
      Host: example.tld
      Accept: application/json
      Authorization: Basic <Base64 Encoded Basic Auth>

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "creationTime": "2018-07-29T11:59:29-05:00",
        "enabled": true,
        "token": "b94cf5c7-cddc-4610-9d4c-6b8e04088ae8",
        "version": 0
      }

   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
   :reqheader Authorization: The encoded basic authorization
   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
   :statuscode 200: user successfully logged in
   :statuscode 401: authorization failed

.. http:post:: /auth/bump

   Bump user login information.

   **Example request**:

   .. sourcecode:: http

      POST /auth/bump HTTP/1.1
      Host: example.tld
      Accept: application/json
      Authorization: Token <Base64(user:userToken)>

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "lastLoginTime": "2018-07-29T12:15:51-05:00"
      }

   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
   :reqheader Authorization: The encoded basic authorization
   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
   :statuscode 200: user last_login_time successfully bumped
   :statuscode 401: authorization failed

.. http:post:: /auth/logout

   Logout a user and remove the provided userToken from valid tokens.

   **Example request**:

   .. sourcecode:: http

      POST /auth/logout HTTP/1.1
      Host: example.tld
      Accept: application/json
      Authorization: Token <Base64(user:userToken)>

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "success": true
      }

   :reqheader Accept: the response content type depends on :mailheader:`Accept` header
   :reqheader Authorization: The encoded basic authorization
   :resheader Content-Type: this depends on :mailheader:`Accept` header of request
   :statuscode 200: user successfully logged out
   :statuscode 401: authorization failed