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