.. _create_vault: 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 | +====================================+===============================+================+========+===============+==================+ | X-Http-Token | StoredSafe token | HTTP Header | String | Yes :sup:`1)` | Preferred method | +------------------------------------+-------------------------------+----------------+--------+---------------+------------------+ | token | StoredSafe token | JSON-encoded | String | Yes :sup:`1)` | Legacy method | +------------------------------------+-------------------------------+----------------+--------+---------------+------------------+ | vaultname (or groupname) :sup:`2)` | Vault name | JSON-encoded | String | Yes :sup:`2)` | See note 2 | +------------------------------------+-------------------------------+----------------+--------+---------------+------------------+ | policy | Password policy for the Vault | JSON-encoded | String | Yes | | +------------------------------------+-------------------------------+----------------+--------+---------------+------------------+ | description | Description of the Vault | JSON-encoded | String | | | +------------------------------------+-------------------------------+----------------+--------+---------------+------------------+ .. note:: :sup:`1)` One of the methods is required. However, the HTTP Header method is the recommended method. .. note:: :sup:`2)` Due to a transition in terms (Vaults was in early releases called Groups), the parameter name "vaultname" or "groupname", which both refer to the same thing (the Vaults name), can be used interchangeably. The response attribute in the current release will always be "groupname". The Response attribute will change to "vaultname" in a later release. Response Attributes ~~~~~~~~~~~~~~~~~~~ +---------------------------+---------------------------------------------------------------+---------+ | Attribute | Description | Type | +===========================+===============================================================+=========+ | VAULT | VAULT | Object | +---------------------------+---------------------------------------------------------------+---------+ | VAULT.(entry) | VAULT entry | Object | +---------------------------+---------------------------------------------------------------+---------+ | VAULT.(entry).id | Vault-ID | String | +---------------------------+---------------------------------------------------------------+---------+ | VAULT.(entry).groupname | Name of Vault | String | +---------------------------+---------------------------------------------------------------+---------+ | VAULT.(entry).policy | Passphrase policy of Vault | String | +---------------------------+---------------------------------------------------------------+---------+ | VAULT.(entry).description | Description of Vault | String | +---------------------------+---------------------------------------------------------------+---------+ | VAULT.(entry).status | Users permission in Vault (bitmap) | String | +---------------------------+---------------------------------------------------------------+---------+ | VAULT.(entry).statustext | Users permission in Vault (Descriptive: Read, Write or Admin) | String | +---------------------------+---------------------------------------------------------------+---------+ | CALLINFO.errorcodes | Number of errors | Integer | +---------------------------+---------------------------------------------------------------+---------+ | CALLINFO.errors | Number of errors | Integer | +---------------------------+---------------------------------------------------------------+---------+ | CALLINFO.general | Information | Array | +---------------------------+---------------------------------------------------------------+---------+ | CALLINFO.handler | Handler used | String | +---------------------------+---------------------------------------------------------------+---------+ | CALLINFO.status | SUCCESS or FAIL | String | +---------------------------+---------------------------------------------------------------+---------+ | CALLINFO.message | Message from handler (if successful) | String | +---------------------------+---------------------------------------------------------------+---------+ | CALLINFO.token | StoredSafe token to be used in subsequent calls | String | +---------------------------+---------------------------------------------------------------+---------+ | DATA | Supplied data in API-call | Object | +---------------------------+---------------------------------------------------------------+---------+ | PARAMS | PARAMS (empty) | Object | +---------------------------+---------------------------------------------------------------+---------+ | ERRORCODES | Error code and text (Only present if errors) | Object | +---------------------------+---------------------------------------------------------------+---------+ | ERRORS | Error code and text (Only present if errors) | Array | +---------------------------+---------------------------------------------------------------+---------+ Examples ~~~~~~~~ Create a new vault to store information about the firewall environment in South Africa. **Request** :: POST /api/1.0/vault x-http-token: your_storedsafe_token { "groupname":"Firewalls in ZA", "policy":"7", "description":"Login information and license keys", } **Response** :: HTTP/2 200 Content-type: application/json; charset=UTF-8 { "CALLINFO": { "errorcodes": 0, "errors": 0, "general": [], "handler": "VaultHandler", "message": "Vault created", "status": "SUCCESS", "token": "rotated_storedsafe_token" }, "DATA": { "description": "Login information and license keys", "groupname": "Firewalls in ZA", "policy": "7", "token": "your_storedsafe_token" }, "HEADERS": { "Accept": "*/*", "Content-Length": "97", "Content-Type": "application/x-www-form-urlencoded", "Host": "safe.domain.cc", "User-Agent": "curl/7.64.1", "X-Http-Token": "your_storedsafe_token" }, "PARAMS": [], "VAULT": [ { "description": "Login information and license keys", "groupname": "Firewalls in ZA", "id": "144", "policy": "7", "status": "4", "statustext": "Admin" } ] }