open-vault/website/content/api-docs/secret/key-management/index.mdx

---
layout: api
page_title: Key Management - Secrets Engines - HTTP API
description: The API documentation for the Key Management secrets engine.
---

# Key Management Secrets Engine (API)

This is the API documentation for the Key Management secrets engine. For general
information about the usage and operation of the secrets engine, please see the
[Key Management secrets engine documentation](/docs/secrets/key-management).

This documentation assumes the Key Management secrets engine is enabled at the
`/keymgmt` path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.

## Create Key

This endpoint creates a named cryptographic key of a specified type. These parameters
set cannot be changed after key creation.

| Method | Path                 |
| :----- | :------------------- |
| `POST` | `/keymgmt/key/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the key to create.
  This is provided as part of the request URL.

- `type` `(string: "rsa-2048")` – Specifies the type of cryptographic key to create. The
  following key types are supported:

  - `aes256-gcm96` - AES-GCM with a 256-bit AES key and a 96-bit nonce (symmetric)
  - `rsa-2048` - RSA with bit size of 2048 (asymmetric)
  - `rsa-3072` - RSA with bit size of 3072 (asymmetric)
  - `rsa-4096` - RSA with bit size of 4096 (asymmetric)
  - `ecdsa-p256` - ECDSA using the P-256 elliptic curve (asymmetric)
  - `ecdsa-p384` - ECDSA using the P-384 elliptic curve (asymmetric)
  - `ecdsa-p521` - ECDSA using the P-521 elliptic curve (asymmetric)

### Sample Payload

```json
{
  "type": "rsa-2048"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/keymgmt/key/example-key
```

## Read Key

This endpoint returns information about a named key. The `keys` object will hold information
regarding each key version. Different information will be returned depending on the key type.
For example, an asymmetric key will return its public key in a PEM encoding.

| Method | Path                 |
| :----- | :------------------- |
| `GET`  | `/keymgmt/key/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the key to read.
  This is provided as part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/keymgmt/key/example-key
```

### Sample Response

```json
{
  "data": {
    "deletion_allowed": false,
    "keys": {
      "1": {
        "creation_time": "2020-11-02T15:54:58.768473-08:00",
        "public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----"
      },
      "2": {
        "creation_time": "2020-11-04T16:58:47.591718-08:00",
        "public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----"
      }
    },
    "latest_version": 2,
    "min_enabled_version": 1,
    "name": "example-key",
    "type": "rsa-2048"
  }
}
```

## List Keys

This endpoint returns a list of all existing keys.

| Method | Path           |
| :----- | :------------- |
| `LIST` | `/keymgmt/key` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/keymgmt/key
```

### Sample Response

```json
{
  "data": {
    "keys": ["example-key"]
  }
}
```

## Update Key

This endpoint updates a named key.

| Method | Path                 |
| :----- | :------------------- |
| `POST` | `/keymgmt/key/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the key to update.
  This is provided as part of the request URL.

- `min_enabled_version` `(int: 0)` – Specifies the minimum enabled version of the key. All
  versions of the key less than the specified version will be disabled for cryptographic
  operations in the KMS provider that the key has been distributed to. Setting this value to
  `0` means that all versions will be enabled.

- `deletion_allowed` `(bool: false)` – Specifies if the key is allowed to be deleted.

### Sample Payload

```json
{
  "min_enabled_version": 0,
  "deletion_allowed": true
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/keymgmt/key/example-key
```

## Rotate Key

This endpoint rotates the version of a named key.

| Method | Path                        |
| :----- | :-------------------------- |
| `POST` | `/keymgmt/key/:name/rotate` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the key to rotate.
  This is provided as part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/keymgmt/key/example-key/rotate
```

## Delete Key

This endpoint deletes a named key. The key must be removed from all KMS providers that it's
been distributed to and have `deletion_allowed` set to `true` in order to be deleted.

| Method   | Path                 |
| :------- | :------------------- |
| `DELETE` | `/keymgmt/key/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the key to delete.
  This is provided as part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/keymgmt/key/example-key
```

## List KMS Providers of Key

This endpoint returns a list of all KMS providers that the named key has been distributed to.
Currently, a key can only be distributed to a single KMS provider.

| Method | Path                     |
| :----- | :----------------------- |
| `LIST` | `/keymgmt/key/:name/kms` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the key.
  This is provided as part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/keymgmt/key/example-key/kms
```

### Sample Response

```json
{
  "data": {
    "keys": ["example-kms"]
  }
}
```

## Create/Update KMS Provider

This endpoint creates or updates a KMS provider. If a KMS provider with the given `name`
does not exist, it will be created. If the KMS provider exists, it will be updated with
the given parameter values.

| Method | Path                 |
| :----- | :------------------- |
| `POST` | `/keymgmt/kms/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the KMS provider to create or update.
  This is provided as part of the request URL.

- `provider` `(string: <required>)` – Specifies the name of a KMS provider that's external to
  Vault. Cannot be changed after creation. For more information about each provider, refer to
  the [KMS Providers](/docs/secrets/key-management#kms-providers) section. The following values
  are supported:

  - `azurekeyvault`
  - `awskms`
  - `gcpckms`

### Common Parameters

There are common parameters that expect different values depending on the specified `provider`.
Please reference the API documentation for individual KMS providers to determine which values to
set for each of the parameters listed below.

- `key_collection` `(string: <required>)` – Refers to a location to store keys in the specified
  `provider`. Cannot be changed after creation. The expected value for this parameter will differ
  depending on the specified `provider`.

- `credentials` `(map<string|string>: nil)` – The credentials to use for authentication with
  the specified `provider`. Supplying values for this parameter is optional, as credentials may
  also be specified as environment variables. The expected keys and values for this parameter
  will differ depending on the specified `provider`.

### Sample Payload

```json
{
  "credentials": [
    "client_id=example-client-id",
    "client_secret=example-client-secret",
    "tenant_id=example-tenant-id"
  ],
  "key_collection": "example-keyvault-name",
  "provider": "azurekeyvault"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms
```

## Read KMS Provider

This endpoint returns information about a KMS provider.

| Method | Path                 |
| :----- | :------------------- |
| `GET`  | `/keymgmt/kms/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the KMS provider to read.
  This is provided as part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms
```

### Sample Response

```json
{
  "data": {
    "key_collection": "example-keyvault-name",
    "provider": "azurekeyvault"
  }
}
```

## List KMS Providers

This endpoint returns a list of all existing KMS providers.

| Method | Path           |
| :----- | :------------- |
| `LIST` | `/keymgmt/kms` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/keymgmt/kms
```

### Sample Response

```json
{
  "data": {
    "keys": ["example-kms"]
  }
}
```

## Delete KMS Provider

This endpoint deletes a KMS provider. A KMS provider cannot be deleted until all keys
that have been distributed to it are removed.

| Method   | Path                 |
| :------- | :------------------- |
| `DELETE` | `/keymgmt/kms/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the KMS provider to delete.
  This is provided as part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms
```

## Distribute Key to KMS Provider

This endpoint distributes a named key to the KMS provider. The key will be securely delivered
(i.e., wrapped for protection in transit) following the key import specification of the KMS
provider. The parameters set cannot be changed after the key has been distributed.

| Method | Path                               |
| :----- | :--------------------------------- |
| `POST` | `/keymgmt/kms/:name/key/:key_name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the KMS provider to distribute the given key
  to. This is provided as part of the request URL.

- `key_name` `(string: <required>)` – Specifies the name of the key to distribute to the given KMS
  provider. This is provided as part of the request URL.

- `purpose` `([]string: <required>)` – Specifies the purpose of the key. The purpose defines a set
  of cryptographic capabilities that the key will have in the KMS provider. A key must have at
  least one of the supported purposes. The following values are supported:

  - `encrypt`
  - `decrypt`
  - `sign`
  - `verify`
  - `wrap`
  - `unwrap`

- `protection` `(string: "hsm")` – Specifies the protection of the key. The protection defines
  where cryptographic operations are performed with the key in the KMS provider. The following
  values are supported:

  - `hsm`
  - `software`

### Sample Payload

```json
{
  "protection": "hsm",
  "purpose": "encrypt,decrypt"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key
```

## Read Key in KMS Provider

This endpoint returns information about a key that's been distributed to a KMS provider.

| Method | Path                               |
| :----- | :--------------------------------- |
| `GET`  | `/keymgmt/kms/:name/key/:key_name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the KMS provider. This is provided as
  part of the request URL.

- `key_name` `(string: <required>)` – Specifies the name of the key. This is provided as part
  of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key
```

### Sample Response

```json
{
  "data": {
    "name": "example-key-<unix_timestamp>",
    "protection": "hsm",
    "purpose": "encrypt,decrypt",
    "versions": {
      "1": "c96a8956194f4632bc3837b64a1b45b1",
      "2": "01ce657d33f64eb38f9432be543f3f52"
    }
  }
}
```

## List Keys in KMS Provider

This endpoint returns a list of all keys that have been distributed to the given KMS
provider. Many keys can be distributed to a single KMS provider.

| Method | Path                     |
| :----- | :----------------------- |
| `LIST` | `/keymgmt/kms/:name/key` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the KMS provider.
  This is provided as part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key
```

### Sample Response

```json
{
  "data": {
    "keys": ["example-key"]
  }
}
```

## Remove Key from KMS Provider

This endpoint removes a named key from the KMS provider. This will only delete the key from
the KMS provider. The key will still exist in the secrets engine and can be redistributed to
a KMS provider at a later time. To permanently delete the key from the secrets engine, the
[Delete Key](#delete-key) API must be invoked.

| Method   | Path                               |
| :------- | :--------------------------------- |
| `DELETE` | `/keymgmt/kms/:name/key/:key_name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the KMS provider. This is provided as
  part of the request URL.

- `key_name` `(string: <required>)` – Specifies the name of the key. This is provided as part
  of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key
```