.. _list_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      |
+================+==================+================+========+===========+==================+
| X-Http-Token   | StoredSafe token | HTTP Header    | String | :sup:`1)` | Preferred method |
+----------------+------------------+----------------+--------+-----------+------------------+
| token          | StoredSafe token | URL-parameter  | String | :sup:`1)` | Legacy method    |
+----------------+------------------+----------------+--------+-----------+------------------+

.. note:: :sup:`1)` One of the methods is required.

Response Attributes
~~~~~~~~~~~~~~~~~~~

+---------------------+---------------------------------------------------------------+---------+
|      Attribute      |                          Description                          |  Type   |
+=====================+===============================================================+=========+
| VAULTS              | Vault                                                         | Array   |
+---------------------+---------------------------------------------------------------+---------+
| VAULTS.id           | Vault-ID                                                      | String  |
+---------------------+---------------------------------------------------------------+---------+
| VAULTS.groupname    | Name of Vault                                                 | String  |
+---------------------+---------------------------------------------------------------+---------+
| VAULTS.policy       | Passphrase policy of Vault                                    | String  |
+---------------------+---------------------------------------------------------------+---------+
| VAULTS.description  | Description of Vault                                          | String  |
+---------------------+---------------------------------------------------------------+---------+
| VAULTS.status       | Users permission in Vault (bitmap)                            | String  |
+---------------------+---------------------------------------------------------------+---------+
| VAULTS.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  |
+---------------------+---------------------------------------------------------------+---------+
| HEADERS             | HTTP Headers                                                  | Object  |
+---------------------+---------------------------------------------------------------+---------+
| DATA                | Supplied data in API-call                                     | Object  |
+---------------------+---------------------------------------------------------------+---------+
| PARAMS              | PARAMS (empty)                                                | Array   |
+---------------------+---------------------------------------------------------------+---------+
| ERRORCODES          | Error code and text (Only present if errors)                  | Object  |
+---------------------+---------------------------------------------------------------+---------+
| ERRORS              | Error code and text (Only present if errors)                  | Array   |
+---------------------+---------------------------------------------------------------+---------+

Examples
~~~~~~~~

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

**Request**

::

    GET /api/1.0/vault
    x-http-token: your_storedsafe_token

**Response**

::

    HTTP/2 200
    Content-type: application/json; charset=UTF-8
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "GroupHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": {
            "token": "your_storedsafe_token"
        },
        "HEADERS": {
            "Accept": "*/*",
            "Host": "safe.domain.cc",
            "User-Agent": "curl/7.64.1",
            "X-Http-Token": "your_storedsafe_token"
        },
        "PARAMS": [],
        "VAULTS": [
            {
              "id": "4",
              "groupname": "Vault number uno",
              "policy": "7",
              "description": "Descriptive text about the vault",
              "status": "1",
              "statustext": "Read"
            },
            {
              "id": "1",
              "groupname": "Vault number due",
              "policy": "13",
              "description": "Descriptive text about the vault",
              "status": "2",
              "statustext": "Write"
            },
            {
              "id": "19",
              "groupname": "Vault number tre",
              "policy": "2",
              "description": "Descriptive text about the vault",
              "status": "4",
              "statustext": "Admin"
            }
        ]
    }