backport of commit 184a4e4 (#17702)

Co-authored-by: Bernhard Kaindl <[email protected]>

website/content/api-docs/secret/ssh.mdx

@@ -820,6 +820,17 @@ $ curl \
 This endpoint signs an SSH public key based on the supplied parameters, subject
 to the restrictions contained in the role named in the endpoint.
 
+It is similar to the endpoint `/ssh/issue/:name`. Instead of issuing new
+SSH credentials, this returns a certificate for the given SSH public key.
+
+The issued certificate uses the defaults specified in the role named in
+this endpoint. Where not restricted by the parameters of this role, the
+parameters of the issued certificate can be further customized in this API call.
+
+~> **Note**: The issued certificate is returned but _not_ stored by Vault.
+   If you do not save it from the response, request it again by repeating
+   this request.
+
 | Method | Path              |
 | :----- | :---------------- |
 | `POST` | `/ssh/sign/:name` |
@@ -887,11 +898,18 @@ $ curl \
 
 ## Generate Certificate and Key
 
-This endpoint generates a new set of credentials (private key and certificate)
-based on the role named in the endpoint.
+This endpoint issues a new set of SSH credentials (private key and certificate).
+
+It is similar to the endpoint `/ssh/sign/:name`: Instead of signing an existing
+SSH public key, it generates and issues new SSH credentials (key and certificate).
+
+The issued certificate uses the defaults specified in the role named in
+this endpoint. Where not restricted by the parameters of this role, the
+parameters of the issued certificate can be further customized in this API call.
 
-~> **Note**: The private key is _not_ stored. If you do not save the private
-   key from the response, you will need to request a new certificate.
+~> **Note**: The issued credentials are returned but _not_ stored by Vault.
+   If you do not save them from the response, issue new credentials by using
+   this request again. This endpoint is available with Vault version 1.12+.
 
 | Method | Path               |
 | :----- | :----------------  |