Project

General

Profile

API v1.0 documentation

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. Supports Ansible 2.4 or better.

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 , 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 , 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

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/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

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/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? String
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 Comment
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 Comment
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:

  1. The user has the capability to create Vaults. (Write capability on user)
  2. The user is a Data Custodian (Admin permission) of the Vault
  3. 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:

  1. 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:

  1. 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:

  1. 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
        }
      }
    },
    "0": {
      "INFO": {
        "id": "0",
        "name": "Person",
        "ico": "person",
        "active": true,
        "wb": true
      },
      "STRUCTURE": {
        "pnr": {
          "translation": "Personnummer",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "namn": {
          "translation": "Namn",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "adress": {
          "translation": "Adress",
          "type": "textarea",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "cryptedinfo": {
          "translation": "Sensitive info",
          "type": "textarea",
          "encrypted": true,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": true,
          "cc": false,
          "nc": true
        }
      }
    },
    "4": {
      "INFO": {
        "id": "4",
        "name": "Login",
        "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
        }
      }
    },
    "10": {
      "INFO": {
        "id": "10",
        "name": "Short login",
        "ico": "server",
        "active": true,
        "ed": true,
        "wb": false,
        "jp": true
      },
      "STRUCTURE": {
        "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
        }
      }
    },
    "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
        }
      }
    },
    "3": {
      "INFO": {
        "id": "3",
        "name": "File",
        "ico": "file",
        "active": true,
        "wb": true,
        "jp": true
      },
      "STRUCTURE": {
        "file1": {
          "translation": "File",
          "type": "file",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "description": {
          "translation": "Description",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        }
      }
    },
    "5": {
      "INFO": {
        "id": "5",
        "name": "Quicknote",
        "ico": "person",
        "active": true,
        "wb": true
      },
      "STRUCTURE": {
        "name": {
          "translation": "Namn",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "progress": {
          "translation": "Slutförd",
          "type": "progress",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        }
      }
    },
    "6": {
      "INFO": {
        "id": "6",
        "name": "PKI",
        "ico": "crt",
        "active": true,
        "wb": true
      },
      "STRUCTURE": {
        "cn": {
          "translation": "Common Name (CN)",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "validfrom": {
          "translation": "Valid from",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "validto": {
          "translation": "Valid to",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "alertafter": {
          "translation": "Alert from",
          "type": "text",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        },
        "passphrase": {
          "translation": "Passphrase",
          "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
        }
      }
    },
    "7": {
      "INFO": {
        "id": "7",
        "name": "Certificate",
        "ico": "crt",
        "active": true,
        "wb": true,
        "jp": true
      },
      "STRUCTURE": {
        "certificate": {
          "translation": "Certificate",
          "type": "file",
          "encrypted": false,
          "show": true,
          "policy": false,
          "alarm": false,
          "opt": false,
          "cc": false,
          "nc": false
        }
      }
    },
    "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
        }
      }
    },
    "9": {
      "INFO": {
        "id": "9",
        "name": "PIN code",
        "ico": "pin",
        "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
        },
        "pincode": {
          "translation": "PIN Code",
          "type": "text-passwdgen",
          "encrypted": true,
          "show": true,
          "policy": true,
          "alarm": true,
          "opt": false,
          "cc": true,
          "nc": true
        }
      }
    }
  },
  "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" 
  }
}