.. _edit_vault:

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      |
+====================================+===============================+================+=========+===============+==================+
| X-Http-Token                       | StoredSafe token              | HTTP Header    | String  | :sup:`1)`     | Preferred method |
+------------------------------------+-------------------------------+----------------+---------+---------------+------------------+
| token                              | StoredSafe token              | JSON-encoded   | String  | :sup:`1)`     | Legacy method    |
+------------------------------------+-------------------------------+----------------+---------+---------------+------------------+
| vault-id                           | Vault-id of the Vault         | URL-paramater  | Integer | Yes           |                  |
+------------------------------------+-------------------------------+----------------+---------+---------------+------------------+
| 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  | Yes           |                  |
+------------------------------------+-------------------------------+----------------+---------+---------------+------------------+

.. 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
~~~~~~~~

Change the name and description of an existing Vault.

**Request**

::

    PUT /api/1.0/vault/178
    x-http-token: your_storedsafe_token
    { 
      "groupname":"Firewalls in South Africa (ZA)", 
      "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 updated",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": {
            "description": "Login information and license keys.",
            "groupname": "Firewalls in ZA",
            "token": "your_storedsafe_token"
        },
        "HEADERS": {
            "Accept": "*/*",
            "Content-Length": "99",
            "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": "13",
                "status": "4",
                "statustext": "Admin"
            }
        ]
    }