.. _read_key:

Method: Read Key
----------------

Description
~~~~~~~~~~~

This endpoint returns information about a named encryption key.

.. note:: Only meta-data regarding the key is returned (not the key).
.. note:: This endpoint requires at least :ref:`Read<bits>` permission in the affected vault.

URL Syntax
~~~~~~~~~~

/api/{version}/transparent/:vaultid/keys/:name

HTTP Method
~~~~~~~~~~~

GET

Successful HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~

200

Parameters
~~~~~~~~~~

+----------------+------------------+----------------+--------+---------+-----------+------------------+
| Parameter name |   Description    | Parameter type |  Type  | Default | Mandatory |     Comment      |
+================+==================+================+========+=========+===========+==================+
| X-Http-Token   | StoredSafe token | HTTP Header    | String |         | :sup:`1)` | Preferred method |
+----------------+------------------+----------------+--------+---------+-----------+------------------+
| token          | StoredSafe token | JSON-encoded   | String |         | :sup:`1)` | Legacy method    |
+----------------+------------------+----------------+--------+---------+-----------+------------------+
| vaultid        | Vault-ID         | URL-encoded    | String |         | Yes       |                  |
+----------------+------------------+----------------+--------+---------+-----------+------------------+
| name           | Key name         | JSON-encoded   | String |         | Yes       |                  |
+----------------+------------------+----------------+--------+---------+-----------+------------------+

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

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

+-----------------------+------------------------------------+---------+
|       Attribute       |            Description             |  Type   |
+=======================+====================================+=========+
| 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.token        | Rotated StoredSafe token :sup:`1)` | String  |
+-----------------------+------------------------------------+---------+
| CALLINFO.version      | Key version                        | String  |
+-----------------------+------------------------------------+---------+
| CALLINFO.objectid     | Object-ID                          | String  |
+-----------------------+------------------------------------+---------+
| KEYS                  | Keys                               | Array   |
+-----------------------+------------------------------------+---------+
| KEYS.name             | Key name                           | String  |
+-----------------------+------------------------------------+---------+
| KEYS.key_version      | Key version                        | String  |
+-----------------------+------------------------------------+---------+
| KEYS.type             | Key type                           | String  |
+-----------------------+------------------------------------+---------+
| KEYS.allow_backup     | Key can be backed up               | String  |
+-----------------------+------------------------------------+---------+
| KEYS.allow_export     | Key can be exported                | String  |
+-----------------------+------------------------------------+---------+
| KEYS.allow_delete     | Key can be deleted                 | String  |
+-----------------------+------------------------------------+---------+
| KEYS.supports_signing | Key supports signing               | String  |
+-----------------------+------------------------------------+---------+
| KEYS.info             | Key information                    | String  |
+-----------------------+------------------------------------+---------+
| DATA                  | Supplied data in prior API-call    | String  |
+-----------------------+------------------------------------+---------+
| HEADERS.(headers)     | HTTP Headers                       | String  |
+-----------------------+------------------------------------+---------+
| PARAMS                | Route parameters (empty)           | Array   |
+-----------------------+------------------------------------+---------+
| ERRORCODES            | Error code and text :sup:`2)`      | Object  |
+-----------------------+------------------------------------+---------+
| ERRORS                | Error code and text :sup:`2)`      | Array   |
+-----------------------+------------------------------------+---------+

.. note:: | :sup:`1)` Token to be used in subsequent calls
   | :sup:`2`) Only present if errors

Examples
~~~~~~~~

Read meta-data for the key named ``my-new-key``, in the vault (vault-id) 179.

**Request**

::

   GET /api/1.0/transparent/179/keys/my-new-key
   x-http-token: your_storedsafe_token

**Response**

::

   HTTP/2 201
   Content-type: application/json; charset=UTF-8
   {
       "CALLINFO": {
           "errorcodes": 0,
           "errors": 0,
           "general": [],
           "handler": "EncryptionHandler",
           "status": "SUCCESS",
           "token": "rotated_storedsafe_token",
       },
       "KEYS": {
           {
               "name": "my-new-key",
               "type": "aes256-gcm96",
               "key_version": "1"
               "info": "My new key",
               "allow_backup": "false",
               "allow_export": "false",
               "allow_delete": "false",
               "supports_signing": "false",
               "objectid": "8743"
           },
       },
       "DATA": {
           "vaultid": "179",
           "token": "your_storedsafe_token",
       },
       "HEADERS": {
           "Accept": "*/*",
           "Content-Length": "169",
           "Content-Type": "application/json",
           "Host": "safe.domain.cc",
           "User-Agent": "curl/7.64.1",
           "X-Http-Token": "your_storedsafe_token"
       },
       "PARAMS": []
   }