API v1.0 documentation¶

Table of contents
API v1.0 documentation
Introduction
- Welcome to the StoredSafe API
- Open Source and StoredSafe
Authentication
Server Address
Providing Parameters
HTTP/1.1 Status Code Definitions
JSON Responses
The Internet is unreliable
Limitations
REST Requests
Resource: Authentication
Resource: Vaults
Resource: Objects
Resource: Templates
- Method: List all Templates
- Method: Retreive a Template
Resource: Miscellaneous functions

Introduction¶

Welcome to the StoredSafe API¶

The StoredSafe API is a way for you to automate your interaction with the StoredSafe system. With the API, you can create your own scripts or applications with most of the functionality you can find inside StoredSafe.

The StoredSafe API is RESTlike and HTTP-based. Basically, this means that the communication is made through normal HTTP requests.

Open Source and StoredSafe¶

StoredSafe develops and maintains some Open source code projects at GitHub, which can be used as reference when coding.

Currently the following projects has been published:

tokenhandler logins and aquires a token used for subsequent REST API calls to a StoredSafe instance.
x509-vacuumer locates, retrieves and stores X.509 certificates in StoredSafe.
csv-importer assists in importing objects via CSV files to StoredSafe.
ssh-storedsafe let's a user login to a remote server using SSH after obtaining the required credentials (password) from StoredSafe.
ansible-storedsafe is a lookup module for information stored in StoredSafe.
vault-storedsafe-client is an ansible vault password client script helper when using ansible-vault to encrypt playbooks or variables.
storedsafe-ruby is a StoredSafe REST-API class library in Ruby
hiera-storedsafe is a Hiera backend to retrieve secrets from Password StoredSafe

Authentication¶

User credentials¶

Authentication is needed in order to use the StoredSafe API, and for this a StoredSafe account is required. The credentials used for accessing the API are the same used to StoredSafe - in other words your login id and your pass phrase.

API Key¶

You will also need an application key - API key (The API keys can be generated by a StoredSafe System Administrator from the system console).

The authentication method for user credentials is a POST request using JSON data with the required credentials. Upon successful authentication a token will be returned, this token needs be used for all subsequent requests. (Hence this is a RESTlike API, not RESTful)

You generate your application key inside the StoredSafe control panel. It is supposed to be unique on an application basis, not user basis. This means that if you produce an application and then distribute it to the public, all users of this application should use the same application key (API key).

The application key (API key) is provided as part of the authentication data.

Two-factor Authentication (2FA)¶

StoredSafe requires each user to use 2FA to authenticate at login. Currently two different methods exists, OTP (Yubico) and TOTP.

Yubico OTP¶

A Yubico OTP is a 44-character, one use, secure, 128-bit encrypted Public ID and Password. The OTP is comprised of two major parts: the first 12 characters remain constant and represent the Public ID of the YubiKey device itself. The remaining 32 characters make up a unique passcode for each OTP generated.

Example output from a YubiKey where the button has been pressed three times

cccjgjgkhcbbirdrfdnlnghhfgrtnnlgedjlftrbdeut
cccjgjgkhcbbgefdkbbditfjrlniggevfhenublfnrev
cccjgjgkhcbbcvchfkfhiiuunbtnvgihdfiktncvlhck

The passcode is generated from a multitude of random sources, including counters for both YubiKey sessions and OTPs generated. When a Yubico OTP is verified, the session and OTP counter values are compared to last values submitted. If the counters are less than the previously used values the OTP is rejected. Copying an OTP will not allow another user to spoof a YubiKey — the counter value will allow the validation server to know which OTPs have already been used.

Example¶

Example: Your account is foo@example.com, the chosen pass phrase is ThisIsAPrettyLousyPassPhrase, the API key is My-API-Key and the OTP is OhMyCouldThisReallyBeAnOTP.

Request

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

Response

    < HTTP/1.1 200 OK
    < Content-Length: 571
    < Content-Type: application/json
    < {
    < "DATA": {
    <   "username": "foo@example.com",
    <   "keys": "ThisIsAPrettyLousyPassPhraseMy-API-KeyOhMyCouldThisReallyBeAnOTP" 
    <  },
    <  "PARAMS": [
    <  ],
    <  "CALLINFO": {
    <     "token": "StoredSafe-Token",
    <     "fingerprint": "<PGP fingerprint>",
    <     "userid": "42",
    <     "password": "ThisIsAPrettyLousyPassPhrase",
    <     "userstatus": "396",
    <     "username": "sven",
    <     "fullname": "Sven Test",
    <     "timeout": 3600000,
    <     "filesupport": 3,
    <     "handler": "AuthHandler",
    <     "status": "SUCCESS" 
    <  }
    < }

Python Code Example¶

"This is too much to read. I just want to get started right now! Give me a simple example!"

Here is a short example of how you can use the API with Python when using Yobico OTP.

#!/usr/bin/python
# -*- coding: utf-8 -*-
import httplib
import ssl
import json

loginJson = {
        'username':'foo@example.com',
        'keys':'ThisIsAPrettyLousyPassPhrase' + 'My-API-Key' + 'OhMyCouldThisReallyBeAnOTP'
}
c = httplib.HTTPSConnection('api.storedsafe.com')
c.request("POST", "/api/1.0/auth", json.dumps(loginJson))
response = c.getresponse()
print response.status, response.reason
data = response.read()
jsonObject = json.loads(data)

TOTP¶

Time-based One-Time Password algorithm (TOTP) is an algorithm that computes a one-time password from a shared secret key and the current time. It has been adopted as Internet Engineering Task Force standard RFC 6238, and is a part of Initiative For Open Authentication (OATH).

TOTP is used by numerous application, Google Authenticator and Microsoft Authenticator being two common examples.

Example¶

Example: Your account is foo@example.com, the chosen pass phrase is ThisIsAPrettyLousyPassPhrase, the API key is My-API-Key and the TOTP is 123456.

Request

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

Response

    < HTTP/1.1 200 OK
    < Content-Length: 571
    < Content-Type: application/json
    < {
    < "DATA": {
    <   "username": "foo@example.com",
    >   "passphrase":"ThisIsAPrettyLousyPassPhrase",
    >   "otp":"123456",
    >   "apikey":"My-API-Key",
    >   "logintype":"totp" 
    <  },
    <  "PARAMS": [
    <  ],
    <  "CALLINFO": {
    <     "token": "StoredSafe-Token",
    <     "fingerprint": "<PGP fingerprint>",
    <     "userid": "42",
    <     "password": "ThisIsAPrettyLousyPassPhrase",
    <     "userstatus": "396",
    <     "username": "sven",
    <     "fullname": "Sven Test",
    <     "timeout": 3600000,
    <     "filesupport": 3,
    <     "handler": "AuthHandler",
    <     "status": "SUCCESS" 
    <  }
    < }

Python Code Example¶

"This is too much to read. I just want to get started right now! Give me a simple example!"

Here is a short example of how you can use the API with Python when using TOTP.

#!/usr/bin/python
# -*- coding: utf-8 -*-
import httplib
import ssl
import json

loginJson = {
        'username':'foo@example.com',
        'passphrase':"ThisIsAPrettyLousyPassPhrase',
        'otp':'123456',
        'apikey':'My-API-Key',
        'logintype':'totp'
}
c = httplib.HTTPSConnection('api.storedsafe.com')
c.request("POST", "/api/1.0/auth", json.dumps(loginJson))
response = c.getresponse()
print response.status, response.reason
data = response.read()
jsonObject = json.loads(data)

Server Address¶

The base server address is: !https://<your.storedsafe.tld>/api/

Please note that HTTPS is required. You will not be able to connect through unencrypted HTTP.

Providing Parameters¶

GET requests should provide their parameters as a query string, part of the URL or as HTTP headers.

POST, PUT and DELETE requests should provide their parameters in JSON-encoded. This should be part of the body.

The encoding of the query string should be standard URL-encoding, as provided by various programming libraries.

HTTP/1.1 Status Code Definitions¶

The HTTP status code returned by a successful API request is defined in the documentation for that method. Usually, this will be 200 OK.

If something goes wrong, other codes may be returned. The API uses standard HTTP/1.1 status codes defined by RFC 2616.

JSON Responses¶

All responses are sent JSON-encoded. The specific responses (successful ones) are described in the documentation section for each method.

However, if something goes wrong, our standard JSON error message (together with an appropriate status code) follows this format:

{
  "ERRORS": [
    "Auth error" 
  ],
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "handler": "<Handler>",
    "status": "FAIL" 
  }
}

The Internet is unreliable¶

Networks in general are unreliable, and particularly one as large and complex as the Internet. Your application should not assume it will get an answer. There may be timeouts.

Limitations¶

The file handling methods are not documented, since they are still being developed.
We do not support "Expect: 100-continue" header from RFC 7231, section 5.1.1: Expect.
We do not support chunked transfer encoding - "Transfer-Encoding: chunked"

REST Requests¶

Below you can find descriptions and examples for all methods.

Resource: Authentication¶

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
login.DATA	DATA	Object
login.DATA.username	Supplied username	String
login.DATA.keys	Supplied Passphrase, API-key and Yubico OTP	String	Only valid for Yubico OTP
login.DATA.passphrase	Supplied passphrase	String	Only valid for TOTP or SMC
login.DATA.otp	Supplied OTP	String	Only valid for TOTP
login.DATA.apikey	Supplied API key	String	Only valid for TOTP or SMC
login.DATA.logintype	The string "totp" or "smc_rest" (smartcard)	String	Only valid for TOTP or SMC
login.PARAMS	PARAMS (empty)	Object
login.CALLINFO	CALLINFO	Object
login.CALLINFO.token	StoredSafe API token, used for subsequent calls	String
login.CALLINFO.fingerprint	PGP fingerprint of logged in user	String
login.CALLINFO.userid	Numerical user-id	String
login.CALLINFO.password	Pass phrase of logged in user	String
login.CALLINFO.userstatus	Status bits for logged in user	String
login.CALLINFO.username	Username of logged in user	String
login.CALLINFO.fullname	Full name of logged in user	String
login.CALLINFO.timeout	How long the token is valid (in microseconds)	Integer
login.CALLINFO.filesupport	If file handling supported, how many templates use file storage	String
login.CALLINFO.handler	Used handler	String
login.CALLINFO.status	Status of the request	String

Example using HOTP¶

Request

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

Response

HTTP/1.1 200 OK
Content-Length: 571
Content-Type: application/json
{
 "DATA": {
   "username": "foo@example.com",
   "keys": "ThisIsAPrettyLousyPassPhraseMy-API-KeyOhMyCouldThisReallyBeAnOTP" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
     "token": "StoredSafe-Token",
     "fingerprint": "<PGP fingerprint>",
     "userid": "42",
     "password": "ThisIsAPrettyLousyPassPhrase",
     "userstatus": "396",
     "username": "sven",
     "fullname": "Sven Test",
     "timeout": 3600000,
     "filesupport": 3,
     "handler": "AuthHandler",
     "status": "SUCCESS" 
  }
}

Example using TOTP¶

Request

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

Response

HTTP/1.1 200 OK
Content-Length: 571
Content-Type: application/json
{
 "DATA": {
   "username": "foo@example.com",
   "passphrase":"ThisIsAPrettyLousyPassPhrase",
   "otp":"123456",
   "apikey":"My-API-Key",
   "logintype":"totp" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
     "token": "StoredSafe-Token",
     "fingerprint": "<PGP fingerprint>",
     "userid": "42",
     "password": "ThisIsAPrettyLousyPassPhrase",
     "userstatus": "396",
     "username": "sven",
     "fullname": "Sven Test",
     "timeout": 3600000,
     "filesupport": 3,
     "handler": "AuthHandler",
     "status": "SUCCESS" 
  }
}

Method: Log out from StoredSafe¶

Description¶

Log out the currently logged in user.

URL Syntax¶

/api/{version}/auth/logout

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	URL-parameter	String	yes

Response Attributes¶

Attribute	Description	Type
login.DATA	DATA	Object
login.DATA.token	Supplied StoredSafe Token	String
login.PARAMS	PARAMS (empty)	Object
login.CALLINFO	CALLINFO	Object
login.CALLINFO.token	StoredSafe API token, used for subsequent calls	String
login.CALLINFO.""	"Bye bye"	String
login.CALLINFO.handler	Used handler	String
login.CALLINFO.status	Status of the request	String

Examples¶

Logout the logged in user.

Request

GET /api/1.0/auth/logout?token=StoredSafe-Token

Response

HTTP/1.1 200 OK
Content-Length: 197
Content-Type: application/json
{
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "": "Bye bye",
    "handler": "AuthHandler",
    "status": "SUCCESS" 
  }
}

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
token	StoredSafe token returned upon successful login	JSON-encoded	String	yes

Response Attributes¶

Attribute	Description	Type
login.DATA	DATA	Object
login.DATA.token	Supplied StoredSafe Token	String
login.PARAMS	PARAMS (empty)	Object
login.CALLINFO	CALLINFO	Object
login.CALLINFO.token	StoredSafe API token, used for subsequent calls	String
login.CALLINFO.""	"SESSION_ALIVE"	String
login.CALLINFO.handler	Used handler	String
login.CALLINFO.status	Status of the request	String

Examples¶

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

Request

POST /api/1.0/auth/check
{ 
  "token": "StoredSafe-Token" 
}

Response

HTTP/1.1 200 OK
Content-Length: 205
Content-Type: application/json
{
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "": "SESSION_ALIVE",
    "handler": "AuthHandler",
    "status": "SUCCESS" 
  }
}

Resource: Vaults¶

Method: List available Vaults¶

Description¶

Returns a list of vaults associated with the logged in user.

URL Syntax¶

/api/{version}/vault

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	URL-parameter	String	yes

Response Attributes¶

Attribute	Description	Type
vault.GROUP	Vault	Object
vault.GROUP.(entry)	Vault entry	Object
vault.GROUP.(entry).id	Vault-ID	String
vault.GROUP.(entry).groupname	Name of Vault	String
vault.GROUP.(entry).policy	Passphrase policy of Vault	String
vault.GROUP.(entry).description	Description of Vault	String
vault.GROUP.(entry).status	Users permission in Vault (bitmap)	String
vault.GROUP.(entry).statustext	Users permission in Vault (Descriptive: Read, Write or Admin)	String
vault.DATA	DATA	Object
vault.DATA.token	StoredSafe Token	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Obtain a list of vaults available to the logged in user.

Request

GET /api/1.0/vault?token=StoredSafe-Token

Response

HTTP/1.1 200 OK
Content-Length: 802
Content-Type: application/json
{
  "GROUP": {
    "4": {
      "id": "4",
      "groupname": "Vault number uno",
      "policy": "7",
      "description": "Descriptive text about the vault",
      "status": "1",
      "statustext": "Read" 
    },
    "1": {
      "id": "1",
      "groupname": "Vault number due",
      "policy": "13",
      "description": "Descriptive text about the vault"",
      "status": "2",
      "statustext": "Write" 
    },
    "19": {
      "id": "19",
      "groupname": "Vault number tre",
      "policy": "2",
      "description": "Descriptive text about the vault",
      "status": "4",
      "statustext": "Admin" 
    }
  },
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "handler": "GroupHandler",
    "status": "SUCCESS" 
  }
}

Method: List objects in a Vault¶

Description¶

Returns a list of all objects in a vault associated with the logged in user.

URL Syntax¶

/api/{version}/vault/{vaultid}

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	URL-parameter	String	yes

Response Attributes¶

Attribute	Description	Type
vault.GROUP	Vault	Object
vault.GROUP.(entry)	Vault entry	Object
vault.GROUP.(entry).id	Vault-ID	String
vault.GROUP.(entry).groupname	Name of Vault	String
vault.GROUP.(entry).policy	Passphrase policy of Vault	String
vault.GROUP.(entry).description	Description of Vault	String
vault.GROUP.(entry).status	Users permission in Vault (bitmap)	String
vault.GROUP.(entry).statustext	Users permission in Vault (Descriptive: Read, Write or Admin)	String
vault.OBJECT	OBJECT	Object
vault.OBJECT.(entry)	OBJECT entry	Object
vault.OBJECT.(entry).id	Object-ID	String
vault.OBJECT.(entry).parentid	Parent-ID	String
vault.OBJECT.(entry).templateid	Template-ID	String
vault.OBJECT.(entry).groupid	Vault-ID	String
vault.OBJECT.(entry).status	Status (Active, Follows policy)	String
vault.OBJECT.(entry).objectname	Name of object	String
vault.OBJECT.(entry).filename	Filename (if a file)	String
vault.OBJECT.(entry).children	Any children	String
vault.OBJECT.(entry).notes	Encrypted notes	String
vault.OBJECT.(entry).tags	Tags associated with the object	String
vault.OBJECT.(entry).alarmed	Should an alarm sound if object is decrypted?	String
vault.OBJECT.(entry).public	Public data (Depends on Template used, see supplied TEMPLATESINFO)	Object
vault.TEMPLATESINFO	TEMPLATESINFO	Object
vault.TEMPLATESINFO.(entry)	TEMPLATESINFO Object	Object
vault.TEMPLATESINFO.(entry).INFO	INFO Object	Object
vault.TEMPLATESINFO.(entry).INFO.id	Template-ID	String
vault.TEMPLATESINFO.(entry).INFO.name	Name of template	String
vault.TEMPLATESINFO.(entry).INFO.ico	Icon used for template	String
vault.TEMPLATESINFO.(entry).INFO.active	Active?	Boolean
vault.TEMPLATESINFO.(entry).INFO.wb	Use workbench for edit? (Always use "ed" if false.	Boolean
vault.TEMPLATESINFO.(entry).INFO.ed	Edit directly? (no subitems)	Boolean
vault.TEMPLATESINFO.(entry).INFO.jp	Jump to parent on save?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE	STRUCTURE Object	Object
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field)	STRUCTURE Object	Object
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).translation	Descriptive text (english)	String
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).type	Type of element (text, textarea, text-passwdgen, file)	String
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).encrypted	Is field encrypted?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).show	Show field normally or only in workbench?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).policy	Should field honor Vaults password policy?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).alarm	Should alarm sound if object is decrypted?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).opt	Is this an optional field or is it required to be filled?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).cc	Needs to be changed to be considered unseen?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).nc	Encrypted fields needs to be clicked to be revealed?	Boolean
vault.DATA	DATA	Object
vault.DATA.token	StoredSafe Token	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Obtain a list of all objects in a vault available to the logged in user.

Request

GET /api/1.0/vault/4?token=StoredSafe-Token

Response

HTTP/1.1 200 OK
Content-Length: 2442
Content-Type: application/json
{
  "GROUP": {
    "4": {
      "id": "4",
      "groupname": "Vault number uno",
      "policy": "7",
      "description": "Descriptive text about the vault",
      "status": "1",
      "statustext": "Read" 
    }
  },
  "OBJECT": {
    "6": {
      "id": "6",
      "parentid": "0",
      "templateid": "1",
      "groupid": "4",
      "status": "128",
      "objectname": "test-server2.example.com",
      "filename": "",
      "children": "0",
      "notes": false,
      "tags": "www",
      "alarmed": false,
      "public": {
        "host": "test-server2.example.com",
        "username": "Administrator",
        "info": "Last changed from IP 1.2.3.4" 
      }
    },
    "683": {
      "id": "683",
      "parentid": "0",
      "templateid": "1001",
      "groupid": "4",
      "status": "1152",
      "objectname": "Non alios suo modulo metire.",
      "filename": "",
      "children": "0",
      "notes": false,
      "tags": "",
      "alarmed": false,
      "public": {
        "host": "Non alios suo modulo metire.",
        "ip": "Non alios suo modulo metire.",
        "username": "Non alios suo modulo metire.",
        "info": "Non alios suo modulo metire." 
      }
    },
    "682": {
      "id": "682",
      "parentid": "0",
      "templateid": "1001",
      "groupid": "4",
      "status": "1152",
      "objectname": "Oculus animi index.",
      "filename": "",
      "children": "0",
      "notes": false,
      "tags": "",
      "alarmed": false,
      "public": {
        "host": "Oculus animi index.",
        "ip": "Oculus animi index.",
        "username": "Oculus animi index.",
        "info": "Oculus animi index." 
      }
    },
    "684": {
      "id": "684",
      "parentid": "0",
      "templateid": "1001",
      "groupid": "4",
      "status": "1152",
      "objectname": "Usus magister est optimus.",
      "filename": "",
      "children": "0",
      "notes": false,
      "tags": "",
      "alarmed": false,
      "public": {
        "host": "Usus magister est optimus.",
        "ip": "Usus magister est optimus.",
        "username": "Usus magister est optimus.",
        "info": "Usus magister est optimus." 
      }
    }
  },
  "TEMPLATESINFO": {
    "1": {
      "INFO": {
        "id": "1",
        "name": "Server",
        "ico": "server",
        "active": true,
        "wb": true
      },
      "STRUCTURE": {
        "host": {
          "translation": "Host / IP",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "username": {
          "translation": "Username",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "password": {
          "translation": "Password",
          "type": "text-passwdgen",
          "encrypted": true,
          "show": true,
          "policy": true,
          "alarm": true,
          "opt": false,
          "cc": true,
          "nc": true
        },
        "info": {
          "translation": "Information",
          "type": "textarea",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        },
        "cryptedinfo": {
          "translation": "Sensitive info",
          "type": "textarea",
          "encrypted": true,
          "show": false,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        }
      }
    },
    "1001": {
      "INFO": {
        "id": "1001",
        "name": "Server/IP",
        "ico": "server",
        "active": true,
        "wb": true
      },
      "STRUCTURE": {
        "host": {
          "translation": "Host",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "ip": {
          "translation": "IP",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "username": {
          "translation": "Username",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false,
          "log": true
        },
        "password": {
          "translation": "Password",
          "type": "text-passwdgen",
          "encrypted": true,
          "show": true,
          "policy": true,
          "alarm": true,
          "opt": false,
          "cc": true,
          "nc": true
        },
        "info": {
          "translation": "Information",
          "type": "textarea",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        },
        "cryptedinfo": {
          "translation": "Sensitive info",
          "type": "textarea",
          "encrypted": true,
          "show": false,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        }
      }
    }
  },
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "handler": "GroupHandler",
    "status": "SUCCESS" 
  }
}

Method: Create a Vault¶

Description¶

Constructs a new Vault with a unique encryption key. The authenticated user need to have the "Create Vault" capability, if method is successful, the authenticated user will have Data Custodian (Admin) rights and be the first (and only) member of the Vault.

URL Syntax¶

/api/{version}/vault

HTTP Method¶

POST

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory
token	StoredSafe token returned upon successful login	JSON-encoded	String	yes
groupname	Vault name	JSON-encoded	String	yes
policy	Password policy for the Vault	JSON-encoded	String	yes
description	Description of the Vault	JSON-encoded	String	yes

Response Attributes¶

Attribute	Description	Type
vault.GROUP	GROUP	Object
vault.GROUP.(entry)	GROUP entry	Object
vault.GROUP.(entry).id	Vault-ID	String
vault.GROUP.(entry).groupname	Name of Vault	String
vault.GROUP.(entry).policy	Passphrase policy of Vault	String
vault.GROUP.(entry).description	Description of Vault	String
vault.GROUP.(entry).status	Users permission in Vault (bitmap)	String
vault.GROUP.(entry).statustext	Users permission in Vault (Descriptive: Read, Write or Admin)	String
vault.DATA	DATA	Object
vault.DATA.token	StoredSafe Token	String
vault.DATA.groupname	Name of Vault	String
vault.DATA.policy	Passphrase policy of Vault	String
vault.DATA.description	Description of Vault	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.token	StoredSafe token	String
vault.CALLINFO.message	Status message from API	String
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Create a new vault to store information about the firewall environment in South Africa.

Request

POST /api/1.0/vault
{ 
  "groupname":"Firewalls in ZA", 
  "policy":"7",
  "description":"Login information and license keys",
  "token":"StoredSafe-Token" 
}

Response

HTTP/1.1 200 OK
Content-Length: 598
Content-Type: application/json
{
  "GROUP": {
    "179": {
      "id": "179",
      "groupname": "Firewalls in ZA",
      "policy": "7",
      "description": "Login information and license keys",
      "status": "4",
      "statustext": "Admin" 
    }
  },
  "DATA": {
    "token": "StoredSafe-Token",
    "groupname": "Firewalls in ZA",
    "policy": "7",
    "description": "Login information and license keys" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "message": "Vault created",
    "handler": "GroupHandler",
    "status": "SUCCESS" 
  }
}

Method: Edit a Vault¶

Description¶

Change information about an existing Vault, such as the Vaults name, description or password policy associated with content in the Vault.

URL Syntax¶

/api/{version}/vault/{vault-id}

HTTP Method¶

PUT

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory
token	StoredSafe token returned upon successful login	JSON-encoded	String	yes
groupname	Vault name	JSON-encoded	String	no
policy	Password policy for the Vault	JSON-encoded	String	no
description	Description of the Vault	JSON-encoded	String	no

Response Attributes¶

Attribute	Description	Type
vault.GROUP	GROUP	Object
vault.GROUP.(entry)	GROUP entry	Object
vault.GROUP.(entry).id	Vault-ID	String
vault.GROUP.(entry).groupname	Name of Vault	String
vault.GROUP.(entry).policy	Passphrase policy of Vault	String
vault.GROUP.(entry).description	Description of Vault	String
vault.GROUP.(entry).status	Users permission in Vault (bitmap)	String
vault.GROUP.(entry).statustext	Users permission in Vault (Descriptive: Read, Write or Admin)	String
vault.DATA	DATA	Object
vault.DATA.token	StoredSafe Token	String
vault.DATA.groupname	Name of Vault	String
vault.DATA.description	Description of Vault	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.token	StoredSafe token	String
vault.CALLINFO.message	Status message from API	String
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Change the name and description of an existing Vault.

Request

PUT /api/1.0/vault/178
{ 
  "groupname":"Firewalls in South Africa (ZA)", 
  "description":"Login information and license keys." 
  "token":"StoredSafe-Token" 
}

Response

HTTP/1.1 200 OK
Content-Length: 611
Content-Type: application/json
{
  "GROUP": {
    "178": {
      "id": "178",
      "groupname": "Firewalls in South Africa (ZA)",
      "policy": "0",
      "description": "Login information and license keys.",
      "status": "4",
      "statustext": "Admin" 
    }
  },
  "DATA": {
    "token": "StoredSafe-Token",
    "groupname": "Firewalls in South Africa (ZA)",
    "description": "Login information and license keys." 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "message": "Vault updated",
    "handler": "GroupHandler",
    "status": "SUCCESS" 
  }
}

Method: Delete a Vault¶

Description¶

Deletes a Vault.

A user with the correct capabilities, Write in this case, can delete a Vault, if the following conditions are met:

The user has the capability to create Vaults. (Write capability on user)
The user is a Data Custodian (Admin permission) of the Vault
The Vault is empty

URL Syntax¶

/api/{version}/vault/{vault-id}

HTTP Method¶

DELETE

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	JSON-encoded	String	yes

Response Attributes¶

Attribute	Description	Type
vault.DATA	DATA	Object
vault.DATA.token	StoredSafe Token	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.token	StoredSafe token	String
vault.CALLINFO.message	Status message from API	String
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Delete an empty Vault.

Request

DELETE /api/1.0/vault/178
{ 
  "token":"StoredSafe-Token" 
}

Response

HTTP/1.1 200 OK
Content-Length: 212
Content-Type: application/json
{
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "message": "Vault deleted",
    "handler": "GroupHandler",
    "status": "SUCCESS" 
  }
}

Resource: Objects¶

Method: List Objects¶

Description¶

List all unencrypted information regarding an object. (Use the decrypt method to decrypt encrypted fields.)

URL Syntax¶

/api/{version}/object/{object-id}

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	URL-parameter	String	yes
children	Also list childrens	URL-parameter	Boolean	no	Defaults to false

Response Attributes¶

Attribute	Description	Type
vault.OBJECT	OBJECT	Object
vault.OBJECT.(entry)	OBJECT entry	Object
vault.OBJECT.(entry).id	Object-ID	String
vault.OBJECT.(entry).parentid	Parent-ID	String
vault.OBJECT.(entry).templateid	Template-ID	String
vault.OBJECT.(entry).groupid	Vault-ID	String
vault.OBJECT.(entry).status	Status (Active, Follows policy)	String
vault.OBJECT.(entry).objectname	Name of object	String
vault.OBJECT.(entry).filename	Filename (if a file)	String
vault.OBJECT.(entry).children	Any children	String
vault.OBJECT.(entry).notes	Encrypted notes	String
vault.OBJECT.(entry).tags	Tags associated with the object	String
vault.OBJECT.(entry).alarmed	Should an alarm sound if object is decrypted?	String
vault.OBJECT.(entry).public	Public data (Depends on Template used, see supplied TEMPLATESINFO)	Object
vault.TEMPLATESINFO	TEMPLATESINFO	Object
vault.TEMPLATESINFO.(entry)	TEMPLATESINFO Object	Object
vault.TEMPLATESINFO.(entry).INFO	INFO Object	Object
vault.TEMPLATESINFO.(entry).INFO.id	Template-ID	String
vault.TEMPLATESINFO.(entry).INFO.name	Name of template	String
vault.TEMPLATESINFO.(entry).INFO.ico	Icon used for template	String
vault.TEMPLATESINFO.(entry).INFO.active	Active?	Boolean
vault.TEMPLATESINFO.(entry).INFO.wb	Use workbench for edit? (Always use "ed" if false.	Boolean
vault.TEMPLATESINFO.(entry).INFO.ed	Edit directly? (no subitems)	Boolean
vault.TEMPLATESINFO.(entry).INFO.jp	Jump to parent on save?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE	STRUCTURE Object	Object
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field)	STRUCTURE Object	Object
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).translation	Descriptive text (english)	String
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).type	Type of element (text, textarea, text-passwdgen, file)	String
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).encrypted	Is field encrypted?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).show	Show field normally or only in workbench?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).policy	Should field honor Vaults password policy?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).alarm	Should alarm sound if object is decrypted?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).opt	Is this an optional field or is it required to be filled?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).cc	Needs to be changed to be considered unseen?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).nc	Encrypted fields needs to be clicked to be revealed?	Boolean
vault.DATA.token	StoredSafe Token	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Retrieve all non-encrypted information about Object-ID 489

Request

GET /api/1.0/object/489?token=StoredSafe-Token

Response

HTTP/1.1 200 OK
Content-Length: 1397
Content-Type: application/json
{
  "OBJECT": {
    "489": {
      "id": "489",
      "parentid": "0",
      "templateid": "8",
      "groupid": "179",
      "status": "128",
      "objectname": "Disaster Recovery Instructions",
      "filename": "",
      "children": "0",
      "notes": false,
      "tags": "",
      "alarmed": false,
      "public": {
        "name": "Disaster Recovery Instructions" 
      }
    }
  },
  "TEMPLATESINFO": {
    "8": {
      "INFO": {
        "id": "8",
        "name": "Note",
        "ico": "note",
        "active": true,
        "ed": true,
        "wb": false,
        "jp": true
      },
      "STRUCTURE": {
        "name": {
          "translation": "Name",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "note": {
          "translation": "Note",
          "type": "textarea",
          "encrypted": true,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": true
        }
      }
    }
  },
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "handler": "ObjectHandler",
    "status": "SUCCESS" 
  }
}

Method: Retreive Objects¶

Description¶

Obtain all information regarding an object and optionally decrypt encrypted fields.

URL Syntax¶

/api/{version}/object/{object-id}

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	URL-parameter	String	yes
decrypt	Request decryption of encrypted fields	URL-parameter	Boolean	no

Response Attributes¶

Attribute	Description	Type
vault.OBJECT	OBJECT	Object
vault.OBJECT.(entry)	OBJECT entry	Object
vault.OBJECT.(entry).id	Object-ID	String
vault.OBJECT.(entry).parentid	Parent-ID	String
vault.OBJECT.(entry).templateid	Template-ID	String
vault.OBJECT.(entry).groupid	Vault-ID	String
vault.OBJECT.(entry).status	Status (Active, Follows policy)	String
vault.OBJECT.(entry).objectname	Name of object	String
vault.OBJECT.(entry).filename	Filename (if a file)	String
vault.OBJECT.(entry).children	Any children	String
vault.OBJECT.(entry).notes	Encrypted notes	String
vault.OBJECT.(entry).tags	Tags associated with the object	String
vault.OBJECT.(entry).alarmed	Should an alarm sound if object is decrypted?	String
vault.OBJECT.(entry).public	Public data (Depends on Template used, see supplied TEMPLATESINFO)	Object
vault.TEMPLATESINFO	TEMPLATESINFO	Object
vault.TEMPLATESINFO.(entry)	TEMPLATESINFO Object	Object
vault.TEMPLATESINFO.(entry).INFO	INFO Object	Object
vault.TEMPLATESINFO.(entry).INFO.id	Template-ID	String
vault.TEMPLATESINFO.(entry).INFO.name	Name of template	String
vault.TEMPLATESINFO.(entry).INFO.ico	Icon used for template	String
vault.TEMPLATESINFO.(entry).INFO.active	Active?	Boolean
vault.TEMPLATESINFO.(entry).INFO.wb	Use workbench for edit? (Always use "ed" if false.	Boolean
vault.TEMPLATESINFO.(entry).INFO.ed	Edit directly? (no subitems)	Boolean
vault.TEMPLATESINFO.(entry).INFO.jp	Jump to parent on save?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE	STRUCTURE Object	Object
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field)	STRUCTURE Object	Object
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).translation	Descriptive text (english)	String
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).type	Type of element (text, textarea, text-passwdgen, file)	String
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).encrypted	Is field encrypted?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).show	Show field normally or only in workbench?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).policy	Should field honor Vaults password policy?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).alarm	Should alarm sound if object is decrypted?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).opt	Is this an optional field or is it required to be filled?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).cc	Needs to be changed to be considered unseen?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).nc	Encrypted fields needs to be clicked to be revealed?	Boolean
vault.DATA.token	StoredSafe Token	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Retrieve all information about Object-ID 489, decrypt any encrypted information.

Request

GET /api/1.0/object/489?token=StoredSafe-Token&decrypt=true

Response

HTTP/1.1 200 OK
Content-Length: 1518
Content-Type: application/json
{
  "OBJECT": {
    "489": {
      "id": "489",
      "parentid": "0",
      "templateid": "8",
      "groupid": "179",
      "status": "128",
      "objectname": "Disaster Recovery Instructions",
      "filename": "",
      "children": "0",
      "notes": false,
      "tags": "",
      "alarmed": false,
      "public": {
        "name": "Disaster Recovery Instructions" 
      }
      "crypted": {
        "note": "Are located in the right drawer, just inside the DC" 
      }
    }
  },
  "TEMPLATESINFO": {
    "8": {
      "INFO": {
        "id": "8",
        "name": "Note",
        "ico": "note",
        "active": true,
        "ed": true,
        "wb": false,
        "jp": true
      },
      "STRUCTURE": {
        "name": {
          "translation": "Name",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "note": {
          "translation": "Note",
          "type": "textarea",
          "encrypted": true,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": true
        }
      }
    }
  },
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "handler": "ObjectHandler",
    "status": "SUCCESS" 
  }
}

Method: Create Objects¶

Description¶

Create a new Object in an existing Vault.

A user can create (update, or delete) objects in a Vault, if the following conditions are met:

The user has been assigned Write permission in the Vault by the Data Custodian (a user with the Admin capability) of the Vault.

URL Syntax¶

/api/{version}/object

HTTP Method¶

POST

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	JSON-encoded	String	yes
templateid	Template-ID	JSON-encoded	String	yes
groupid	Vault-ID	JSON-encoded	String	yes
parentid	Parent-ID	JSON-encoded	String	yes
objectname	Name of Object	JSON-encoded	String	yes
host	Name of host (from template)	JSON-encoded	String	yes	Depends on template being used
username	Username (from template)	JSON-encoded	String	yes	Depends on template being used
info	Additional unencrypted info (from template)	JSON-encoded	String	yes	Depends on template being used
password	Password (from template)	JSON-encoded	String	yes	Depends on template being used
cryptedinfo	Additional encrypted info (from template)	JSON-encoded	String	yes	Depends on template being used

Response Attributes¶

Attribute	Description	Type
vault.DATA	DATA	Object
vault.DATA.token	StoredSafe Token	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.token	StoredSafe token	String
vault.CALLINFO.objectid	Newly created Object-ID	String
vault.CALLINFO.message	Status message from API	String
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Create a new object in Vault-ID 179 using Template-id 1 (A Server template).

Request

POST /api/1.0/object
{
    "token": "StoredSafe-Token",
    "templateid": "1",
    "groupid": "179",
    "parentid": "0",
    "objectname": "firewall2.za.example.com",
    "host": "firewall2.za.example.com",
    "username": "root",
    "info": "The second pfSense fw protecting the ZA branch.",
    "password": "~[vN8x9W6~7P367vm53Y",
    "cryptedinfo": "iLO password is #q:vP74A+VRmW5Ueu12O" 
}

Response

HTTP/1.1 200 OK
Content-Length: 635
Content-Type: application/json
{
  "DATA": {
    "token": "StoredSafe-Token",
    "templateid": "1",
    "parentid": "0",
    "groupid": "179",
    "objectname": "firewall2.za.example.com",
    "host": "firewall2.za.example.com",
    "username": "root",
    "info": "The second pfSense fw protecting the ZA branch.",
    "password": "~[vN8x9W6~7P367vm53Y",
    "cryptedinfo": "iLO password is #q:vP74A+VRmW5Ueu12O" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "objectid": 491,
    "message": "Object successfully saved",
    "handler": "ObjectHandler",
    "status": "SUCCESS" 
  }
}

Method: Edit Objects¶

Description¶

Edit an existing Object.

A user can update (create or delete) objects in a Vault, if the following conditions are met:

The user has been assigned Write permission in the Vault by the Data Custodian (a user with the Admin capability) of the Vault.

URL Syntax¶

/api/{version}/object/{object-id}

HTTP Method¶

PUT

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	JSON-encoded	String	yes
templateid	Template-ID	JSON-encoded	String	yes
groupid	Vault-ID	JSON-encoded	String	yes
parentid	Parent-ID	JSON-encoded	String	yes
objectname	Name of Object	JSON-encoded	String	yes
host	Name of host (from template)	JSON-encoded	String	yes	Depends on template being used
username	Username (from template)	JSON-encoded	String	yes	Depends on template being used
info	Additional unencrypted info (from template)	JSON-encoded	String	yes	Depends on template being used
password	Password (from template)	JSON-encoded	String	yes	Depends on template being used
cryptedinfo	Additional encrypted info (from template)	JSON-encoded	String	yes	Depends on template being used

Response Attributes¶

Attribute	Description	Type
vault.DATA	DATA	Object
vault.DATA.token	StoredSafe Token	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.token	StoredSafe token	String
vault.CALLINFO.objectid	Newly created Object-ID	String
vault.CALLINFO.message	Status message from API	String
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Change the password of Object-ID 492

Request

PUT /api/1.0/object/492
{
    "token": "StoredSafe-Token",
    "templateid": "1",
    "groupid": "179",
    "parentid": "0",
    "objectname": "firewall2.za.example.com",
    "host": "firewall2.za.example.com",
    "username": "root",
    "info": "The second pfSense fw protecting the ZA branch.",
    "password": "quad-sue-rude-abut-guy-shod-beat-dime-chew-rear-see-new",
    "cryptedinfo": "iLO password is #q:vP74A+VRmW5Ueu12O" 
}

Response

HTTP/1.1 200 OK
Content-Length: 628
Content-Type: application/json
{
  "DATA": {
    "token": "StoredSafe-Token",
    "templateid": "1",
    "groupid": "179",
    "parentid": "0",
    "objectname": "firewall2.za.example.com",
    "host": "firewall2.za.example.com",
    "username": "root",
    "info": "The second pfSense fw protecting the ZA branch.",
    "password": "quad-sue-rude-abut-guy-shod-beat-dime-chew-rear-see-new",
    "cryptedinfo": "iLO password is #q:vP74A+VRmW5Ueu12O" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "0": "BAD_POLICY",
    "handler": "ObjectHandler",
    "status": "SUCCESS" 
  }
}

Method: Delete Objects¶

Description¶

Delete an Object in an existing Vault.

A user can delete (create, or update) objects in a Vault, if the following conditions are met:

The user has been assigned Write permission in the Vault by the Data Custodian (a user with the Admin capability) of the Vault.

URL Syntax¶

/api/{version}/object/{object-id}

HTTP Method¶

DELETE

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	JSON-encoded	String	yes

Response Attributes¶

Attribute	Description	Type
vault.DATA	DATA	Object
vault.DATA.token	StoredSafe Token	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Delete object 491.

Request

DELETE /api/1.0/object/491
{
    "token": "StoredSafe-Token" 
}

Response

HTTP/1.1 200 OK
Content-Length: 251
Content-Type: application/json
{
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "": "DELETED",
    "handler": "ObjectHandler",
    "status": "SUCCESS" 
  }
}

Method: Search Objects¶

Description¶

Search in unencrypted data to locate Objects.

URL Syntax¶

/api/{version}/find

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	URL-parameter	String	yes
needle	Search string	URL-parameter	String	yes	Case insensitive

Response Attributes¶

Attribute	Description	Type
vault.OBJECT	OBJECT	Object
vault.OBJECT.(entry)	OBJECT entry	Object
vault.OBJECT.(entry).id	Object-ID	String
vault.OBJECT.(entry).parentid	Parent-ID	String
vault.OBJECT.(entry).templateid	Template-ID	String
vault.OBJECT.(entry).groupid	Vault-ID	String
vault.OBJECT.(entry).status	Status (Active, Follows policy)	String
vault.OBJECT.(entry).objectname	Name of object	String
vault.OBJECT.(entry).filename	Filename (if a file)	String
vault.OBJECT.(entry).children	Any children	String
vault.OBJECT.(entry).notes	Encrypted notes	String
vault.OBJECT.(entry).tags	Tags associated with the object	String
vault.OBJECT.(entry).alarmed	Should an alarm sound if object is decrypted?	String
vault.OBJECT.(entry).public	Public data (Depends on Template used, see supplied TEMPLATESINFO)	Object
vault.TEMPLATESINFO	TEMPLATESINFO	Object
vault.TEMPLATESINFO.(entry)	TEMPLATESINFO Object	Object
vault.TEMPLATESINFO.(entry).INFO	INFO Object	Object
vault.TEMPLATESINFO.(entry).INFO.id	Template-ID	String
vault.TEMPLATESINFO.(entry).INFO.name	Name of template	String
vault.TEMPLATESINFO.(entry).INFO.ico	Icon used for template	String
vault.TEMPLATESINFO.(entry).INFO.active	Active?	Boolean
vault.TEMPLATESINFO.(entry).INFO.wb	Use workbench for edit? (Always use "ed" if false.	Boolean
vault.TEMPLATESINFO.(entry).INFO.ed	Edit directly? (no subitems)	Boolean
vault.TEMPLATESINFO.(entry).INFO.jp	Jump to parent on save?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE	STRUCTURE Object	Object
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field)	STRUCTURE Object	Object
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).translation	Descriptive text (english)	String
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).type	Type of element (text, textarea, text-passwdgen, file)	String
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).encrypted	Is field encrypted?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).show	Show field normally or only in workbench?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).policy	Should field honor Vaults password policy?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).alarm	Should alarm sound if object is decrypted?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).opt	Is this an optional field or is it required to be filled?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).cc	Needs to be changed to be considered unseen?	Boolean
vault.TEMPLATESINFO.(entry).STRUCTURE.(template-field).nc	Encrypted fields needs to be clicked to be revealed?	Boolean
vault.DATA.token	StoredSafe Token	String
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Search thru Vaults this user has at least Read access to, for the string "pfsense".

Request

GET /api/1.0/find?token=StoredSafe-Token&needle=pfSense

Response

HTTP/1.1 200 OK
Content-Length: 2760
Content-Type: application/json
{
  "OBJECT": {
    "490": {
      "id": "490",
      "parentid": "0",
      "templateid": "1",
      "groupid": "179",
      "status": "128",
      "objectname": "firewall.za.example.com",
      "filename": "",
      "children": "0",
      "notes": false,
      "tags": "",
      "alarmed": false,
      "public": {
        "host": "firewall.za.example.com",
        "username": "root",
        "info": "The pfSense fw protecting the ZA branch." 
      }
    },
    "492": {
      "id": "492",
      "parentid": "0",
      "templateid": "1",
      "groupid": "179",
      "status": "128",
      "objectname": "firewall2.za.example.com",
      "filename": "",
      "children": "0",
      "notes": false,
      "tags": "",
      "alarmed": false,
      "public": {
        "host": "firewall2.za.example.com",
        "username": "root",
        "info": "The second pfSense fw protecting the ZA branch." 
      }
    }
  },
  "TEMPLATESINFO": {
    "1": {
      "INFO": {
        "id": "1",
        "name": "Server",
        "ico": "server",
        "active": true,
        "wb": true
      },
      "STRUCTURE": {
        "host": {
          "translation": "Host / IP",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "username": {
          "translation": "Username",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "password": {
          "translation": "Password",
          "type": "text-passwdgen",
          "encrypted": true,
          "show": true,
          "policy": true,
          "alarm": true,
          "opt": false,
          "cc": true,
          "nc": true
        },
        "info": {
          "translation": "Information",
          "type": "textarea",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        },
        "cryptedinfo": {
          "translation": "Sensitive info",
          "type": "textarea",
          "encrypted": true,
          "show": false,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        }
      }
    }
  },
  "DATA": {
    "token": "StoredSafe-Token",
    "needle": "pfsense" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "handler": "FindHandler",
    "status": "SUCCESS" 
  }
}

Resource: Templates¶

Method: List all Templates¶

Description¶

Obtain list of all available templates.

URL Syntax¶

/api/{version}/template

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	URL-parameter	String	yes

Response Attributes¶

Attribute	Description	Type
vault.TEMPLATE	TEMPLATE	Object
vault.TEMPLATE.(entry)	TEMPLATE entry	Object
vault.TEMPLATE.(entry).INFO	INFO entry	Object
vault.TEMPLATE.(entry).STRUCTURE	STRUCTURE entry	Object
vault.TEMPLATE.(entry).STRUCTURE.(template-field)	Depends on each template	Object
vault.TEMPLATE.(entry).STRUCTURE.(template-field).translation	Descriptive text (english)	String
vault.TEMPLATE.(entry).STRUCTURE.(template-field).type	Type of element (text, textarea, text-passwdgen, file)	String
vault.TEMPLATE.(entry).STRUCTURE.(template-field).encrypted	Is field encrypted?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).show	Show field normally or only in workbench?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).policy	Should field honor Vaults password policy?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).alarm	Should alarm sound if object is decrypted?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).opt	Is this an optional field or is it required to be filled?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).cc	Needs to be changed to be considered unseen?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).nc	Encrypted fields needs to be clicked to be revealed?	Boolean
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Obtain list of all available templates.

Request

GET /api/1.0/template?token=StoredSafe-Token

Response

HTTP/1.1 200 OK
Content-Length: 10896
Content-Type: application/json
{
  "TEMPLATE": {
    "2": {
      "INFO": {
        "id": "2",
        "name": "Folder",
        "ico": "folder",
        "active": true,
        "wb": true
      },
      "STRUCTURE": {
        "name": {
          "translation": "Folder name",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "info": {
          "translation": "Description",
          "type": "textarea",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        }
      }
    },
    "1": {
      "INFO": {
        "id": "1",
        "name": "Server",
        "ico": "server",
        "active": true,
        "wb": true
      },
      "STRUCTURE": {
        "host": {
          "translation": "Host / IP",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "username": {
          "translation": "Username",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "password": {
          "translation": "Password",
          "type": "text-passwdgen",
          "encrypted": true,
          "show": true,
          "policy": true,
          "alarm": true,
          "opt": false,
          "cc": true,
          "nc": true
        },
        "info": {
          "translation": "Information",
          "type": "textarea",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        },
        "cryptedinfo": {
          "translation": "Sensitive info",
          "type": "textarea",
          "encrypted": true,
          "show": false,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        }
      }
    },
    .
    .
  },
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "handler": "TemplateHandler",
    "status": "SUCCESS" 
  }
}

Method: Retreive a Template¶

Description¶

Obtain information about one specific template.

URL Syntax¶

/api/{version}/template/{template-id}

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
token	StoredSafe token returned upon successful login	URL-parameter	String	yes
templateid	ID of template to be retreived	URL-parameter	String	yes

Response Attributes¶

Attribute	Description	Type
vault.TEMPLATE	TEMPLATE	Object
vault.TEMPLATE.(entry)	TEMPLATE entry	Object
vault.TEMPLATE.(entry).INFO	INFO entry	Object
vault.TEMPLATE.(entry).STRUCTURE	STRUCTURE entry	Object
vault.TEMPLATE.(entry).STRUCTURE.(template-field)	Depends on each template	Object
vault.TEMPLATE.(entry).STRUCTURE.(template-field).translation	Descriptive text (english)	String
vault.TEMPLATE.(entry).STRUCTURE.(template-field).type	Type of element (text, textarea, text-passwdgen, file)	String
vault.TEMPLATE.(entry).STRUCTURE.(template-field).encrypted	Is field encrypted?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).show	Show field normally or only in workbench?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).policy	Should field honor Vaults password policy?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).alarm	Should alarm sound if object is decrypted?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).opt	Is this an optional field or is it required to be filled?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).cc	Needs to be changed to be considered unseen?	Boolean
vault.TEMPLATE.(entry).STRUCTURE.(template-field).nc	Encrypted fields needs to be clicked to be revealed?	Boolean
vault.PARAMS	PARAMS (empty)	Object
vault.CALLINFO	CALLINFO	Object
vault.CALLINFO.handler	Used handler	String
vault.CALLINFO.status	Status of the request	String

Examples¶

Retreive Template-ID 1, the Server template.

Request

GET /api/1.0/template/1?token=StoredSafe-Token

Response

HTTP/1.1 200 OK
Content-Length: 1814
Content-Type: application/json
{
  "TEMPLATE": {
    "1": {
      "INFO": {
        "id": "1",
        "name": "Server",
        "ico": "server",
        "active": true,
        "wb": true
      },
      "STRUCTURE": {
        "host": {
          "translation": "Host / IP",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "username": {
          "translation": "Username",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "password": {
          "translation": "Password",
          "type": "text-passwdgen",
          "encrypted": true,
          "show": true,
          "policy": true,
          "alarm": true,
          "opt": false,
          "cc": true,
          "nc": true
        },
        "info": {
          "translation": "Information",
          "type": "textarea",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        },
        "cryptedinfo": {
          "translation": "Sensitive info",
          "type": "textarea",
          "encrypted": true,
          "show": false,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": false
        }
      }
    }
  },
  "DATA": {
    "token": "StoredSafe-Token" 
  },
  "PARAMS": [
  ],
  "CALLINFO": {
    "token": "StoredSafe-Token",
    "handler": "TemplateHandler",
    "status": "SUCCESS" 
  }
}

Resource: Miscellaneous functions¶

Method: Obtain capabilities and permission bits.¶

Description¶

Obtain list of all available capabilities (user) and permission (vaults) bits.

URL Syntax¶

/api/{version}/utils/statusvalues

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
X-Http-Token	StoredSafe token returned upon successful login	HTTP Header	String	*	Preferred method
token	StoredSafe token returned upon successful login	URL-parameter	String	*	Legacy method

*) One of the methods (HTTP Header or URL-parameter) is required.

Response Attributes¶

Attribute	Description	Type
vault.CALLINFO.errorcodes	Number of errors	Integer
vault.CALLINFO.errors	Number of errors	Integer
vault.CALLINFO.general	Information	Array
vault.CALLINFO.handler	Handler used	String
vault.CALLINFO.status	SUCCESS or FAIL	String
vault.CALLINFO.statusbits.userbits.(capability)	Statusbits (users)	Integer
vault.CALLINFO.statusbits.vaultbits.(permission)	Statusbits (vaults)	Integer
vault.CALLINFO.token	StoredSafe token	String
vault.DATA.token	StoredSafe token	String
vault.HEADERS.(headers)	HTTP Headers	String
vault.PARAMS	Route parameters (empty)	Array
vault.ERRORCODES	Error code and text (Only present if errors)	Object
vault.ERRORS	Error code and text (Only present if errors)	Array

Examples¶

Obtain list of all available capabilities (user) and permission (vaults) bits.

Request

GET /api/1.0/utils/statusvalues
x-http-token: StoredSafe-Token

Response

HTTP/2 200
content-type: application/json; charset=UTF-8
{
    "CALLINFO": {
        "errorcodes": 0,
        "errors": 0,
        "general": [],
        "handler": "UtilsHandler",
        "status": "SUCCESS",
        "statusbits": {
            "userbits": {
                "Active": 7,
                "Admin": 2,
                "Alarm": 4,
                "Audit": 3,
                "Changepass": 6,
                "Escrow": 8,
                "Read": 0,
                "Write": 1
            },
            "vaultbits": {
                "Admin": 2,
                "Read": 0,
                "Write": 1
            }
        },
        "token": "StoredSafe-Token" 
    },
    "DATA": {
        "token": "StoredSafe-Token" 
    },
    "HEADERS": {
        "Accept": "*/*",
        "Host": "safe.domain.cc",
        "User-Agent": "curl/7.64.1",
        "X-Http-Token": "StoredSafe-Token" 
    },
    "PARAMS": []
}

Method: Obtain all password policies.¶

Description¶

Obtain list of all available password policies.

URL Syntax¶

/api/{version}/utils/policies

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
X-Http-Token	StoredSafe token returned upon successful login	HTTP Header	String	*	Preferred method
token	StoredSafe token returned upon successful login	URL-parameter	String	*	Legacy method

*) One of the methods (HTTP Header or URL-parameter) is required.

Response Attributes¶

Attribute	Description	Type
vault.CALLINFO.errorcodes	Number of errors	Integer
vault.CALLINFO.errors	Number of errors	Integer
vault.CALLINFO.general	Information	Array
vault.CALLINFO.handler	Handler used	String
vault.CALLINFO.status	SUCCESS or FAIL	String
vault.CALLINFO.policies.(id)	Password policies	Array
vault.CALLINFO.token	StoredSafe token	String
vault.DATA.token	StoredSafe token	String
vault.HEADERS.(headers)	HTTP Headers	String
vault.PARAMS	Route parameters (empty)	Array
vault.ERRORCODES	Error code and text (Only present if errors)	Object
vault.ERRORS	Error code and text (Only present if errors)	Array

Examples¶

Obtain list of all available password policies.

Request

GET /api/1.0/utils/policies
x-http-token: StoredSafe-Token

Response

HTTP/2 200
content-type: application/json; charset=UTF-8
{
    "CALLINFO": {
        "errorcodes": 0,
        "errors": 0,
        "general": [],
        "handler": "UtilsHandler",
        "status": "SUCCESS",
        "policies": [
            {
                "id": 7,
                "name": "High Quality Password (14+ chars, mixed case, number and special)",
                "rules": {
                    "min_length": 14,
                    "min_lowercase_chars": 1,
                    "min_nonalphanumeric_chars": 1,
                    "min_numeric_chars": 1,
                    "min_uppercase_chars": 1
                }
            },
            {
                "id": 8,
                "name": "Good Quality Password (12+ chars, mixed case, number and special))",
                "rules": {
                    "min_length": 12,
                    "min_lowercase_chars": 1,
                    "min_nonalphanumeric_chars": 1,
                    "min_numeric_chars": 1,
                    "min_uppercase_chars": 1
                }
            },
            .
            .
        ],
        "token": "StoredSafe-Token" 
    },
    "DATA": {
        "token": "StoredSafe-Token" 
    },
    "HEADERS": {
        "Accept": "*/*",
        "Host": "safe.domain.cc",
        "User-Agent": "curl/7.64.1",
        "X-Http-Token": "StoredSafe-Token" 
    },
    "PARAMS": []
}

Method: Obtain StoredSafe version.¶

Description¶

Obtain StoredSafe version number and build number.

URL Syntax¶

/api/{version}/utils/version

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
X-Http-Token	StoredSafe token returned upon successful login	HTTP Header	String	*	Preferred method
token	StoredSafe token returned upon successful login	URL-parameter	String	*	Legacy method

*) One of the methods (HTTP Header or URL-parameter) is required.

Response Attributes¶

Attribute	Description	Type
vault.CALLINFO.errorcodes	Number of errors	Integer
vault.CALLINFO.errors	Number of errors	Integer
vault.CALLINFO.general	Information	Array
vault.CALLINFO.handler	Handler used	String
vault.CALLINFO.status	SUCCESS or FAIL	String
vault.CALLINFO.version	Version and build number	String
vault.CALLINFO.token	StoredSafe token	String
vault.DATA.token	StoredSafe token	String
vault.HEADERS.(headers)	HTTP Headers	String
vault.PARAMS	Route parameters (empty)	Array
vault.ERRORCODES	Error code and text (Only present if errors)	Object
vault.ERRORS	Error code and text (Only present if errors)	Array

Examples¶

Obtain list of all available capabilities (user) and permission (vaults) bits.

Request

GET /api/1.0/utils/version
x-http-token: StoredSafe-Token

Response

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

Method: Password generator¶

Description¶

Generates different types of passwords.

URL Syntax¶

/api/{version}/utils/pwgen

HTTP Method¶

GET

Successful HTTP Response¶

200

Parameters¶

Parameter name	Description	Parameter type	Type	Mandatory	Comment
X-Http-Token	StoredSafe token returned upon successful login	HTTP Header	String	*	Preferred method
token	StoredSafe token returned upon successful login	URL-parameter	String	*	Legacy method
type	Type to generate; pronounceable, diceword, opie, secure or pin	URL-parameter	String	Optional
length	Sets desired length	URL-parameter	String	Optional	Valid for pronounceable, secure and pin
language	Select language (en_US or sv_SE)	URL-parameter	String	Optional	Valid for diceword
delimiter	Delimiter between dice words (dash '-', space ' ' or default ',.- _=:')	URL-parameter	String	Optional	Valid for diceword and opie
words	Number of words (diceword)	URL-parameter	String	Optional	Valid for diceword
min_char	Minimum number of characters in a word	URL-parameter	String	Optional	Valid for diceword
max_char	Maximum number of characters in a word	URL-parameter	String	Optional	Valid for diceword
policyid	Try to match this password policy	URL-parameter	String	Optional

*) One of the methods (HTTP Header or URL-parameter) is required.

Generators¶

secure and pronounceable uses Theodore Ts'o classical pwgen
opie uses Thomas Habets fantastic opwgen
diceword uses Fredrik Erikssons eminent pwgen

Defaults¶

No parameters will give type secure and length 40.

Generator	Type	Length	Max length	Default Settings
pin	Integers	4	40
pronounceable	alphanumeric	12	1024
secure	alphanumeric and symbols	40	1024
opie	alpha	128 bit	128 bit	delimiter=space
diceword	alpha, national charactes, numbers and symbols			language=en_US, words=5, min_char=2, max_char=0, delimiter=,.- _=:

Response Attributes¶

Attribute	Description	Type
vault.CALLINFO.errorcodes	Number of errors	Integer
vault.CALLINFO.errors	Number of errors	Integer
vault.CALLINFO.general	Information	Array
vault.CALLINFO.handler	Handler used	String
vault.CALLINFO.status	SUCCESS or FAIL	String
vault.CALLINFO.passphrase	Generated password	String
vault.CALLINFO.length	Length of password	Integer
vault.CALLINFO.type	Password generator used	String
vault.CALLINFO.token	StoredSafe token	String
vault.DATA.token	StoredSafe token	String
vault.HEADERS.(headers)	HTTP Headers	String
vault.PARAMS	Route parameters (empty)	Array
vault.ERRORCODES	Error code and text (Only present if errors)	Object
vault.ERRORS	Error code and text (Only present if errors)	Array

Examples¶

Generates a secure type passwords of 40 characters in length.

Request

GET /api/1.0/utils/pwgen
x-http-token: StoredSafe-Token

Response

HTTP/2 200
content-type: application/json; charset=UTF-8
{
    "CALLINFO": {
        "errorcodes": 0,
        "errors": 0,
        "general": [],
        "handler": "UtilsHandler",
        "status": "SUCCESS",
        "passphrase": "Sz(6Q~si\"`WACS:b\\{[Y~A~Bs+dn\\uTrG5/eG}yf",
        "length": 40,
        "type": "secure" 
        "token": "StoredSafe-Token" 
    },
    "DATA": {
        "token": "StoredSafe-Token" 
    },
    "HEADERS": {
        "Accept": "*/*",
        "Host": "safe.domain.cc",
        "User-Agent": "curl/7.64.1",
        "X-Http-Token": "StoredSafe-Token" 
    },
    "PARAMS": []
}

Files (0)

Project

General

Profile

StoredSafe

Wiki

API v1.0 documentation¶

Introduction¶

Welcome to the StoredSafe API¶

Open Source and StoredSafe¶

Authentication¶

User credentials¶

API Key¶

Two-factor Authentication (2FA)¶

Yubico OTP¶

Example¶

Python Code Example¶

TOTP¶

Example¶

Python Code Example¶

Server Address¶

Providing Parameters¶

HTTP/1.1 Status Code Definitions¶

JSON Responses¶

The Internet is unreliable¶

Limitations¶

REST Requests¶

Resource: Authentication¶

Method: Login to StoredSafe¶

Description¶

URL Syntax¶

HTTP Method¶

Successful HTTP Response¶

Parameters¶

Response Attributes¶

Example using HOTP¶

Example using TOTP¶

Method: Log out from StoredSafe¶

Description¶

URL Syntax¶

HTTP Method¶

Successful HTTP Response¶

Parameters¶

Response Attributes¶

Examples¶

Method: Check if the session is alive¶

Description¶

URL Syntax¶

HTTP Method¶

Successful HTTP Response¶

Parameters¶

Response Attributes¶

Examples¶

Resource: Vaults¶

Method: List available Vaults¶

Description¶

URL Syntax¶

HTTP Method¶

Successful HTTP Response¶

Parameters¶

Response Attributes¶

Examples¶

Method: List objects in a Vault¶

Description¶

URL Syntax¶

HTTP Method¶

Successful HTTP Response¶

Parameters¶

Response Attributes¶

Examples¶

Method: Create a Vault¶

Description¶

URL Syntax¶

HTTP Method¶

Successful HTTP Response¶

Parameters¶

Response Attributes¶

Examples¶

Method: Edit a Vault¶

Description¶

URL Syntax¶