.. _login:

Method: Login to StoredSafe
---------------------------

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

Authenticate to StoredSafe using username, passphrase and a valid token,
could be a Yubico OTP, a TOTP or a smartcard. Returns a token used for
subsequent calls to the API.

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

/api/{version}/auth

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

POST

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

200

Parameters
~~~~~~~~~~

+------------------+-------------------------------------------------------+------------------+----------+--------------+---------------------------------+
| Parameter name   | Description                                           | Parameter type   | Type     | Mandatory    | Comment                         |
+==================+=======================================================+==================+==========+==============+=================================+
| username         | StoredSafe username                                   | JSON-encoded     | String   | yes          |                                 |
+------------------+-------------------------------------------------------+------------------+----------+--------------+---------------------------------+
| keys             | Passphrase, API-key and Yubico OTP                    | JSON-encoded     | String   | Yubico OTP   | **Only** valid for Yubico OTP   |
+------------------+-------------------------------------------------------+------------------+----------+--------------+---------------------------------+
| passphrase       | Passphrase                                            | JSON-encoded     | String   | TOTP, SMC    |                                 |
+------------------+-------------------------------------------------------+------------------+----------+--------------+---------------------------------+
| otp              | OTP                                                   | JSON-encoded     | String   | TOTP         | **Only** valid for TOTP         |
+------------------+-------------------------------------------------------+------------------+----------+--------------+---------------------------------+
| apikey           | API-key                                               | JSON-encoded     | String   | TOTP, SMC    |                                 |
+------------------+-------------------------------------------------------+------------------+----------+--------------+---------------------------------+
| logintype        | Either the string "totp" or "smc\_rest" (smartcard)   | JSON-encoded     | String   | TOTP, SMC    |                                 |
+------------------+-------------------------------------------------------+------------------+----------+--------------+---------------------------------+

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.fingerprint      | PGP fingerprint of logged in user                               | String  |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.userid           | Numerical user-id                                               | String  |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.password         | Pass phrase of logged in user                                   | String  |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.userstatus       | Status bits for logged in user                                  | String  |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.username         | Username of logged in user                                      | String  |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.fullname         | Full name of logged in user                                     | String  |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.timeout          | How long the token is valid (in microseconds)                   | Integer |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.filesupport      | If file handling supported, how many templates use file storage | String  |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.audit.violations | Any system violations                                           | Array   |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.audit.warnings   | Any system related warnings                                     | Array   |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| CALLINFO.version          | StoredSafe version and build number                             | Array   |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| DATA.username             | Supplied username                                               | String  |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| DATA.keys                 | Supplied Passphrase, API-key and Yubico OTP                     | String  | **Only** valid for Yubico OTP  |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| DATA.passphrase           | Supplied passphrase                                             | String  | **Only** valid for TOTP or SMC |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| DATA.otp                  | Supplied OTP                                                    | String  | **Only** valid for TOTP        |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| DATA.apikey               | Supplied API key                                                | String  | **Only** valid for TOTP or SMC |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| DATA.logintype            | The string "totp" or "smc\_rest" (smartcard)                    | String  | **Only** valid for TOTP or SMC |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+
| PARAMS                    | PARAMS (empty)                                                  | Object  |                                |
+---------------------------+-----------------------------------------------------------------+---------+--------------------------------+

Example using HOTP
~~~~~~~~~~~~~~~~~~

Login to StoredSafe and obtain a token used for latter communication.

**Request**

::

    POST /api/1.0/auth
    { 
      "username":"foo@example.com", 
      "keys":"ThisIsAPrettyLousyPassPhraseMy-API-KeyOhMyCouldThisReallyBeAnOTP"
    }

**Response**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "audit": {
                "violations": [],
                "warnings": []
            },
            "errorcodes": 0,
            "errors": 0,
            "fingerprint": "<PGP fingerprint>",
            "userid": "42",
            "password": "ThisIsAPrettyLousyPassPhrase",
            "userstatus": "396",
            "username": "sven",
            "fullname": "Sven Test",
            "timeout": 3600000,
            "filesupport": 3,
            "general": [
                "Your passphrase is weak and should be changed"
            ],
            "handler": "AuthHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token",
            "version": "2.1.0"
        },
        "DATA": {
            "apikey": "abcde12345",
            "username": "foo@example.com",
            "keys": "ThisIsAPrettyLousyPassPhraseMy-API-KeyOhMyCouldThisReallyBeAnOTP"
        },
        "HEADERS": {
            "Accept": "*/*",
            "Content-Length": "107",
            "Content-Type": "application/x-www-form-urlencoded",
            "Host": "safe.domain.cc",
            "User-Agent": "curl/7.64.1"
        },
        "PARAMS": []
    }

Example using TOTP
~~~~~~~~~~~~~~~~~~

Login to StoredSafe and obtain a token used for latter communication.

**Request**

::

    POST /api/1.0/auth
    { 
      "username":"foo@example.com", 
      "passphrase":"ThisIsAPrettyLousyPassPhrase",
      "otp":"123456",
      "apikey":"My-API-Key",
      "logintype":"totp"
    }

**Response**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "audit": {
                "violations": [],
                "warnings": []
            },
            "errorcodes": 0,
            "errors": 0,

            "token": "your_storedsafe_token",
            "fingerprint": "<PGP fingerprint>",
            "userid": "42",
            "password": "ThisIsAPrettyLousyPassPhrase",
            "userstatus": "396",
            "username": "sven",
            "fullname": "Sven Test",
            "timeout": 3600000,
            "filesupport": 3,
            "general": [
                "Your passphrase is weak and should be changed"
            ],
            "handler": "AuthHandler",
            "status": "SUCCESS",
            "version": "2.1.0"
        },
        "DATA": {
            "username": "foo@example.com",
            "passphrase":"ThisIsAPrettyLousyPassPhrase",
            "otp":"123456",
            "apikey":"My-API-Key",
            "logintype":"totp"
        },
        "HEADERS": {
            "Accept": "*/*",
            "Content-Length": "107",
            "Content-Type": "application/x-www-form-urlencoded",
            "Host": "safe.domain.cc",
            "User-Agent": "curl/7.64.1"
        },
        "PARAMS": []
    }