.. _rotate_key:

Method: Rotate Key
------------------

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

This endpoint rotates the named encryption key in the specified vault.
After rotation, new plaintext requests will be encrypted with the new version of the named key.
To upgrade ciphertext to be encrypted with the latest version of the key, use the :ref:`/rewrap<rewrap>` endpoint. 

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

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

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

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

POST

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

201

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         | URL-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.key_version | Latest key version                 | String  |
+----------------------+------------------------------------+---------+
| CALLINFO.objectid    | Object-ID                          | 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
~~~~~~~~

Rotate the key ``my-new-key`` in the vault (vaultid) 179, creating a new 
random encryption key, with a new version number.

**Request**

::

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

**Response**

::

   HTTP/2 200
   Content-type: application/json; charset=UTF-8
   {
       "CALLINFO": {
           "errorcodes": 0,
           "errors": 0,
           "general": [],
           "handler": "EncryptionHandler",
           "status": "SUCCESS",
           "token": "rotated_storedsafe_token",
           "name": "my-new-key",
           "key_version": "2",
           "objectid": "8743"
       },
       "DATA": {
           "name": "my-new-key",
           "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": []
   }