Add api docs for new derivedkeys endpoint

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

@@ -1219,8 +1219,8 @@ 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                           |
-| :----- | :----------------------------- |
+| Method | Path                            |
+| :----- | :------------------------------ |
 | `POST` | `/transit/datakeys/:type/:name` |
 
 ### Path parameters
@@ -1282,6 +1282,78 @@ $ curl \
 }
 ```
 
+## Generate Derived Keys
+
+The derived keys endpoint generates new keys based on the HMAC key associated
+with the provided key name. 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/derivedkeys/: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 keys.
+
+### Request parameters
+
+- `salt` `(string: <required>)` - The salt input to derivation
+
+- `key_index_from` `(int: <required>)` - The starting index for keys to return
+
+- `key_index_to` `(int: <required>)` - The ending index (non-inclusive) for keys to return
+
+- `bits` `(int: 256)` – Specifies the number of bits in the desired keys. Can be
+  128, 256, or 512.
+
+- `key_version` `(int: 0)` – The version of the Vault key to use for encryption
+of the data key. Must be 0 (for latest) or a value greater than or equal to the
+min_encryption_version configured on the key.
+
+- `info` `(string: "")` – The info string input to derivation
+
+### Sample payload
+
+```json
+{
+  "key_index_from": 0,
+  "key_index_to": 1,
+  "salt": "sodium chloride"
+}
+```
+
+### Sample request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request POST \
+    --data @payload.json \
+    http://127.0.0.1:8200/v1/transit/derivedkeys/plaintext/my-key
+```
+
+### Sample response
+
+```json
+{
+  "0": {
+    "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=",
+    "ciphertext": "vault:v1:abcdefgh"
+  },
+  "key_version": 0
+}
+```
+
 ## Generate random bytes
 
 This endpoint returns high-quality random bytes of the specified length.