---
layout: api
page_title: /sys/managed-keys - HTTP API
description: The `/sys/managed-keys` endpoint is used manage the managed keys in Vault.
---

# `/sys/managed-keys`

The `/sys/managed-keys` endpoint is used manage the Managed Key configuration within Vault.
See the [Managed Keys](/docs/enterprise/managed-keys) section for further details on the Managed Keys system.

## List managed keys.

This endpoint lists all the Managed Keys of a certain type within the namespace.

| Method | Path                      |
|:-------|:--------------------------|
| `LIST` | `/sys/managed-keys/:type` |

### Parameters
- `type` `(string: <required>)` – The backend type of keys to be listed.
  Supported options are `pkcs11`.

### Sample Request

```shell-session
$ curl \
    --request LIST \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11
```

### Sample Response

```json
{
  "keys": [
    "hsm-key1",
    "hsm-key2"
  ]
}
```

## Create/Update managed key

An endpoint that will create or update a Managed Key within a given namespace. The :type refers to the backend type
that the key is to use, such as `pkcs11`. The :name argument is unique name within all managed key types in
the namespace.

| Method | Path                            |
|:-------|:--------------------------------|
| `POST` | `/sys/managed-keys/:type/:name` |

### Sample Request

```shell-session
$ curl \
    --request POST \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11/hsm-key1
```

### Generic Parameters
- `name` `(string: <required>)` - A unique lowercase name that serves as identifying the key. Must be
  unique throughout all types in the namespace.

- `type` `(string: <required>)` – The backend type that will be leveraged for the managed key.
  Supported options are `pkcs11`.

- `allow_generate_key` `(string: "false")` - If no existing key can be found in the referenced backend, instructs
  Vault to generate a key within the backend.

- `allow_replace_key` `(string: "false")` - Controls the ability for Vault to replace through generation or importing
  a key into the configured backend even if a key is present, if set to false those operations are forbidden
  if a key exists.

- `allow_store_key` `(string: "false")` - Controls the ability for Vault to generate or import a key within the
  configured backend, if "false" those operations will be forbidden.

- `any_mount` `(string: "false")` - Allow usage from any mount point within the namespace if "true". If "false"
  specific mount points will need their `allowed_managed_keys` parameter to be updated with the key name to
  grant usage.

#### PKCS#11 backend Parameters

 ~> NOTE: The `pkcs11` backend is only available with Vault Enterprise Plus (HSMs) edition

- `type` `(string: "pkcs11")` - To select a PKCS#11 backend, the type parameter must be set to `pkcs11`

- `library` `(string: <required>)` - The name of the `kms_library` stanza to use from Vault's config to
   lookup the local library path. See [kms_library stanza](/docs/configuration/kms-library) for further details.

- `key_label` `(string: <required>)`: The label of the key to use. If the key
  does not exist and generation is enabled, this is the label that will be given
  to the generated key.

- `mechanism` `(string: <required>)` - The encryption/decryption mechanism to use,
  specified as a hexadecimal (prefixed by 0x) string. The following are supported mechanisms
    - `0x1041` `CKM_ECDSA`
    - `0x000D` `CKM_RSA_PKCS_PSS`
    - `0x0009` `CKM_RSA_PKCS_OAEP`
    - `0x0001` `CKM_RSA_PKCS`

- `pin` `(string: <required>)`: The PIN for login.

- `slot` `(string: <slot or token label required>)`: The slot number to use,
  specified as a string in a decimal format (e.g. `"2305843009213693953"`).

  ~> **Note**: Slots are typically listed as hex-decimal values in the OS setup
  utility but this configuration uses their decimal equivalent. For example, using the
  HSM command-line `pkcs11-tool`, a slot listed as `0x2000000000000001`in hex is equal
  to `2305843009213693953` in decimal; these values may be listed shorter or
  differently as determined by the HSM in use.

- `token_label` `(string: <slot or token label required>)`: The slot token label to
  use.

- `curve` `(string: "")` - supplies the curve value when using the `CKM_ECDSA mechanism`.
  The supported values are
    - `P384`
    - `P521`
    - `P256`

- `key_bits` `(int: 0)` - supplies the size in bits of the key when using `CKM_RSA_PKCS_PSS`,
  `CKM_RSA_PKCS_OAEP` or `CKM_RSA_PKCS` as a value for `mechanism`.
  The supported values are
    - 2048
    - 3072
    - 4096

- `force_rw_session` `(string: "false")`: Force all operations to open up
  a read-write session to the HSM. This is a boolean expressed as a string (e.g.
  `"true"`). This key is mainly to work around a limitation within AWS's CloudHSM v5
  pkcs11 implementation.

## Read managed key

This endpoint returns the managed key configuration at the given path.

| Method | Path                            |
|:-------|:--------------------------------|
| `GET`  | `/sys/managed-keys/:type/:name` |

### Parameters
- `name` `(string: <required>)` - The lowercase name identifying the key.

- `type` `(string: <required>)` – The backend type for the managed key.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11/hsm-key1
```

### Sample Response

```json
{
  "UUID": "af0a688e-d2c1-fc07-b365-40325674114d",
  "allow_generate_key": true,
  "allow_replace_key": false,
  "allow_store_key": false,
  "any_mount": false,
  "curve": "",
  "force_rw_session": false,
  "key_bits": 0,
  "key_label": "test-kms-root",
  "library": "softhsm",
  "mechanism": 1,
  "name": "hsm-key1",
  "pin": "redacted",
  "slot": 1,
  "token_label": "",
  "type": "pkcs11"
}
```

## Delete managed key

This endpoint deletes the managed key at the given path provided it is not
listed within any mount point's `allowed_managed_keys`.

| Method   | Path                            |
|:---------|:--------------------------------|
| `DELETE` | `/sys/managed-keys/:type/:name` |

### Parameters
- `name` `(string: <required>)` - The lowercase name identifying the key.

- `type` `(string: <required>)` – The backend type for the managed key.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11/hsm-key1
```