.. _delete_key:

Method: Delete Key
------------------

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

This endpoint deletes a named encryption key in a specified vault.

.. warning:: It will no longer be possible to decrypt any data encrypted with the named key.

.. note:: This endpoint requires at least :ref:`Write<bits>` permission in the affected vault and that the key is marked as :ref:`deleteable<allow_delete>` (``allow_delete``).

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

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

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

DELETE

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

Delete the key ``my-new-key`` from the vault (vault-id) 179.

**Request**

::

   DELETE /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",
       },
       "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": []
   }