.. _check:

Method: Check if the session is alive
-------------------------------------

Description
~~~~~~~~~~~

Check if the session to StoredSafe is alive and if the token is valid,
will also refresh the timeout for the token.

URL Syntax
~~~~~~~~~~

/api/{version}/auth/check

HTTP Method
~~~~~~~~~~~

POST

Successful HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~

200

Parameters
~~~~~~~~~~

+------------------+--------------------+------------------+----------+-------------+--------------------+
| Parameter name   | Description        | Parameter type   | Type     | Mandatory   | Comment            |
+==================+====================+==================+==========+=============+====================+
| X-Http-Token     | StoredSafe token   | HTTP Header      | String   | :sup:`1)`   | Preferred method   |
+------------------+--------------------+------------------+----------+-------------+--------------------+
| token            | StoredSafe token   | JSON-encoded     | String   | :sup:`1)`   | Legacy method      |
+------------------+--------------------+------------------+----------+-------------+--------------------+

.. note:: :sup:`1)` One of the methods is required.

Response Attributes
~~~~~~~~~~~~~~~~~~~

+---------------------+--------------------------------------------------+---------+---------+
|      Attribute      |                   Description                    |  Type   | Comment |
+=====================+==================================================+=========+=========+
| CALLINFO.errorcodes | Number of errors                                 | Integer |         |
+---------------------+--------------------------------------------------+---------+---------+
| CALLINFO.errors     | Number of errors                                 | Integer |         |
+---------------------+--------------------------------------------------+---------+---------+
| CALLINFO.general    | Information                                      | Array   |         |
+---------------------+--------------------------------------------------+---------+---------+
| CALLINFO.handler    | Handler used                                     | String  |         |
+---------------------+--------------------------------------------------+---------+---------+
| CALLINFO.status     | SUCCESS or FAIL                                  | String  |         |
+---------------------+--------------------------------------------------+---------+---------+
| CALLINFO.token      | StoredSafe Token to be used for subsequent calls | String  |         |
+---------------------+--------------------------------------------------+---------+---------+
| CALLINFO.general    | Information                                      | Array   |         |
+---------------------+--------------------------------------------------+---------+---------+
| DATA                | Supplied data in API-call                        | String  |         |
+---------------------+--------------------------------------------------+---------+---------+
| PARAMS              | PARAMS (empty)                                   | Object  |         |
+---------------------+--------------------------------------------------+---------+---------+
| ERRORCODES          | Error code and text (Only present if errors)     | Object  |         |
+---------------------+--------------------------------------------------+---------+---------+
| ERRORS              | Error code and text (Only present if errors)     | Array   |         |
+---------------------+--------------------------------------------------+---------+---------+

Examples
~~~~~~~~

Check if the connection to the server is alive. Effectively prolongs the
life of the token.

**Request**

::

    POST /api/1.0/auth/check
    x-http-token: StoredSafe-Token

**Response**

::

    HTTP/2 200
    Content-type: application/json; charset=UTF-8
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "AuthHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": {
            "token": "your_storedsafe_token"
        },
        "HEADERS": {
            "Accept": "*/*",
            "Host": "safe.domain.cc",
            "User-Agent": "curl/7.64.1",
            "X-Http-Token": "your_storedsafe_token"
        },
        "PARAMS": []
    }