---
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"
}
```

## Test Sign with a managed key

This endpoint allows an operator to validate that a managed key configuration works
by signing and verifying some randomly generated data. No values can be provided to sign,
nor are signed or verified data returned to the caller. If the call returns a successful HTTP
status code, the configuration can be considered valid.

~> **Note**: if key generation is allowed and no existing key can be found, this call will generate the key

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

### 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 POST \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/managed-keys/pkcs11/hsm-key1/test/sign
```


## 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
```