Add docs for new datakeys endpoint

content/vault/v1.21.x (rc)/content/api-docs/secret/transit.mdx

@@ -1201,6 +1201,79 @@ $ curl \
 }
 ```
 
+## Generate multiple data keys
+
+The data keys endpoint generates the specified number of new, high-entropy keys.
+Vault always returns keys encrypted with the provided named and optionally
+returns the associated plaintext.
+
+You can use Vault ACL policies to control which users can retrieve the plaintext
+value of the keys. For example, to allow untrusted users or operations to
+generate keys that are then available to trusted users.
+
+| Method | Path                           |
+| :----- | :----------------------------- |
+| `POST` | `/transit/datakeys/:type/:name` |
+
+### Path parameters
+
+- `type` `(enum: <required>)` – Specifies the type of keys to generate.
+    - `plaintext` - return the plaintext keys along with the ciphertexts
+    - `wrapped` - only return the ciphertext values.
+
+- `name` `(string: <required>)` – Specifies the name of the encryption key to
+  use to encrypt the datakeys.
+
+### Request parameters
+
+- `count` `(int: <required>)` - Specifies the number of keys to generate.
+
+- `bits` `(int: 256)` – Specifies the number of bits in the desired keys. Can be
+  128, 256, or 512.
+
+- `key_version` `(int: 0)` – Specifies the version of the key to use for the
+  operation. Leave `key_version` unset to use the latest version. `key_version`
+  must be unset or greater than or equal to the associated
+  `min_encryption_version` value.
+
+### Sample payload
+
+```json
+{
+  "count": "2"
+}
+```
+
+### Sample request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    --data @payload.json \
+    http://127.0.0.1:8200/v1/transit/datakey/plaintext/my-key
+```
+
+### Sample response
+
+```json
+{
+  "data": {
+    "key_pairs": [
+      {
+        "ciphertext": "vault:v1:MA8yD4Neu2VtwrDbU8rcxPWGvkjK0ARquXyyiNMI+j34RNagvo0cu3l3e1HjEKL55I2k0PfTfAOisZMB",
+        "plaintext": "HT/dnq7RO9c5RloxMHGPDWUjscqdHLa0KAful8X12wg="
+      },
+      {
+        "ciphertext": "vault:v1:yOLlOVe6azNVuoZYARps+RHHJYr5x0Jror6DmjcAcXTFmXwfqiSjaEcl3GNdbofohfKfBawM4jxrtN+3",
+        "plaintext": "0srJIA4MVjNVkm9JR2in8KlMAmN0n+l8RLT7S9W9ESs="
+      }
+    ],
+    "key_version": 1
+  }
+}
+```
+
 ## Generate random bytes
 
 This endpoint returns high-quality random bytes of the specified length.