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