.. _restore_key:

Method: Restore Key
-------------------

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

This endpoint restores a named key from a backup. This will restore all 
information needed to use the the named key (and all it's versions).
It accepts input from the :ref:`/backup<backup_key>` endpoint.

.. note:: This endpoint requires at least :ref:`Write<bits>` permission in the affected vault.

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

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

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

POST

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       |                  |
+----------------+------------------+----------------+--------+---------+-----------+------------------+
| backup         | Backup of key    | 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  |
+---------------------+------------------------------------+---------+
| 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
~~~~~~~~

Restore a previously performed backup of the named key ``my-new-key`` to the vault (vault-id) 2468.

**Request**

::

   POST /api/1.0/transparent/restore/2468/my-new-key
   x-http-token: your_storedsafe_token
   {
        "backup": "nE5hpsaXES36QB057qUeED6EKMbzfbjiy+g2BiZ1yIYJH/1Nv3w76vVZpj2F3Ln3Y77tx6VIuoFAOz5OA+hB+jQYCdqYTBelwFcrklML6nNuPv1XZ1EVKprWOGrheqBZ4j2BB0ScXkS+VzguFQrCpc+CxpzI5WtDnxmbMbkJZLU="
   }

**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"
       },
       "DATA": {
           "backup": "nE5hpsaXES36QB057qUeED6EKMbzfbjiy+g2BiZ1yIYJH/1Nv3w76vVZpj2F3Ln3Y77tx6VIuoFAOz5OA+hB+jQYCdqYTBelwFcrklML6nNuPv1XZ1EVKprWOGrheqBZ4j2BB0ScXkS+VzguFQrCpc+CxpzI5WtDnxmbMbkJZLU=",
           "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": []
   }