KeyVault.deleteKey.txt

.. _keyvault-deletekey-method:

====================
KeyVault.deleteKey()
====================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. method:: KeyVault.deleteKey(UUID)

   Deletes a data encryption key with the specified UUID from the key
   vault associated to the database connection.

   :method:`~KeyVault.deleteKey()` has the following syntax:

   .. code-block:: none

      keyVault = db.getMongo().getKeyVault()
      
      keyVault.deleteKey(UUID("<UUID String>"))

   The :abbr:`UUID (Universally unique identifier)` is a BSON 
   :bsontype:`binary data <Binary>` object with subtype ``4``.

   :returns: A document indicating the number of deleted keys.


Compatibility
-------------

This command is available in deployments hosted in the following
environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-onprem-only.rst


Behavior
--------

Requires Configuring Client-Side Field Level Encryption on Database Connection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/extracts/csfle-requires-enabling-encryption.rst

Example
-------

The following example is intended for rapid evaluation of
client-side field level encryption. For specific examples of using
:method:`KeyVault.deleteKey()` with each supported
:abbr:`KMS (Key Management Service)` provider, see
:ref:`field-level-encryption-data-key-delete`.

.. include:: /includes/csfle-connection-boilerplate-example.rst

Retrieve the :method:`KeyVault <getKeyVault()>` object and
use the :method:`KeyVault.deleteKey()` method to 
delete the data encryption key with matching ``UUID``:

.. code-block:: javascript

   keyVault = encryptedClient.getKeyVault()
   keyVault.deleteKey(UUID("b4b41b33-5c97-412e-a02b-743498346079"))

If successful, :method:`~KeyVault.deleteKey()` returns output similar to
the following:

.. code-block:: json

   { "acknowledged" : true, "deletedCount" : 1 }

.. seealso::

   :ref:`field-level-encryption-data-key-delete`