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",
        "timeout": 14400000,
        "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": []
}