docs(client-secrets-manager): Documentation updates for Secrets Manager

Author: awstools

clients/client-secrets-manager/src/SecretsManager.ts

@@ -36,7 +36,7 @@ export interface CancelRotateSecretCommandOutput extends CancelRotateSecretRespo
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:CancelRotateSecret</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/CancelRotateSecretCommand.ts

@@ -22,8 +22,9 @@ export interface CreateSecretCommandInput extends CreateSecretRequest {}
 export interface CreateSecretCommandOutput extends CreateSecretResponse, __MetadataBearer {}
 
 /**
- * <p>Creates a new secret. A <i>secret</i> is a set of credentials, such as a
- *       user name and password, that you store in an encrypted form in Secrets Manager. The secret also
+ * <p>Creates a new secret. A <i>secret</i> can be a password, a set of
+ *       credentials such as a user name and password, an OAuth token, or other secret information
+ *       that you store in an encrypted form in Secrets Manager. The secret also
  *       includes the connection information to access a database or other service, which Secrets Manager
  *       doesn't encrypt. A secret in Secrets Manager consists of both the protected secret data and the
  *       important information needed to manage the secret.</p>
@@ -33,6 +34,9 @@ export interface CreateSecretCommandOutput extends CreateSecretResponse, __Metad
  *       If you include <code>SecretString</code> or <code>SecretBinary</code>
  *       then Secrets Manager creates an initial secret version and automatically attaches the staging
  *       label <code>AWSCURRENT</code> to it.</p>
+ *          <p>For database credentials you want to rotate, for Secrets Manager to be able to rotate the secret,
+ *       you must make sure the JSON you store in the <code>SecretString</code> matches the <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_secret_json_structure.html">JSON structure of
+ *         a database secret</a>.</p>
  *          <p>If you don't specify an KMS encryption key, Secrets Manager uses the Amazon Web Services managed key
  *       <code>aws/secretsmanager</code>. If this key
  *       doesn't already exist in your account, then Secrets Manager creates it for you automatically. All
@@ -44,10 +48,12 @@ export interface CreateSecretCommandOutput extends CreateSecretResponse, __Metad
  *       and use a customer managed KMS key. </p>
  *          <p>
  *             <b>Required permissions: </b>
- *             <code>secretsmanager:CreateSecret</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *             <code>secretsmanager:CreateSecret</code>. If you
+ *       include tags in the secret, you also need <code>secretsmanager:TagResource</code>.
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
+ *          <p>To encrypt the secret with a KMS key other than <code>aws/secretsmanager</code>, you need <code>kms:GenerateDataKey</code> and <code>kms:Decrypt</code> permission to the key. </p>
  * @example
  * Use a bare-bones client and the command you need to make an API call.
  * ```javascript

clients/client-secrets-manager/src/commands/CreateSecretCommand.ts

@@ -27,7 +27,7 @@ export interface DeleteResourcePolicyCommandOutput extends DeleteResourcePolicyR
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:DeleteResourcePolicy</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/DeleteResourcePolicyCommand.ts

@@ -38,7 +38,7 @@ export interface DeleteSecretCommandOutput extends DeleteSecretResponse, __Metad
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:DeleteSecret</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/DeleteSecretCommand.ts

@@ -27,7 +27,7 @@ export interface DescribeSecretCommandOutput extends DescribeSecretResponse, __M
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:DescribeSecret</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/DescribeSecretCommand.ts

@@ -28,7 +28,7 @@ export interface GetRandomPasswordCommandOutput extends GetRandomPasswordRespons
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:GetRandomPassword</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/GetRandomPasswordCommand.ts

@@ -29,7 +29,7 @@ export interface GetResourcePolicyCommandOutput extends GetResourcePolicyRespons
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:GetResourcePolicy</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/GetResourcePolicyCommand.ts

@@ -34,7 +34,7 @@ export interface GetSecretValueCommandOutput extends GetSecretValueResponse, __M
  *             <code>secretsmanager:GetSecretValue</code>.
  *       If the secret is encrypted using a customer-managed key instead of the Amazon Web Services managed key
  *       <code>aws/secretsmanager</code>, then you also need <code>kms:Decrypt</code> permissions for that key.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/GetSecretValueCommand.ts

@@ -29,7 +29,7 @@ export interface ListSecretVersionIdsCommandOutput extends ListSecretVersionIdsR
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:ListSecretVersionIds</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/ListSecretVersionIdsCommand.ts

@@ -32,7 +32,7 @@ export interface ListSecretsCommandOutput extends ListSecretsResponse, __Metadat
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:ListSecrets</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/ListSecretsCommand.ts

@@ -30,7 +30,7 @@ export interface PutResourcePolicyCommandOutput extends PutResourcePolicyRespons
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:PutResourcePolicy</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/PutResourcePolicyCommand.ts

@@ -46,7 +46,7 @@ export interface PutSecretValueCommandOutput extends PutSecretValueResponse, __M
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:PutSecretValue</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/PutSecretValueCommand.ts

@@ -28,7 +28,7 @@ export interface RemoveRegionsFromReplicationCommandOutput
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:RemoveRegionsFromReplication</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/RemoveRegionsFromReplicationCommand.ts

@@ -26,7 +26,7 @@ export interface ReplicateSecretToRegionsCommandOutput extends ReplicateSecretTo
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:ReplicateSecretToRegions</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/ReplicateSecretToRegionsCommand.ts

@@ -27,7 +27,7 @@ export interface RestoreSecretCommandOutput extends RestoreSecretResponse, __Met
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:RestoreSecret</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example

clients/client-secrets-manager/src/commands/RestoreSecretCommand.ts

@@ -22,27 +22,35 @@ export interface RotateSecretCommandInput extends RotateSecretRequest {}
 export interface RotateSecretCommandOutput extends RotateSecretResponse, __MetadataBearer {}
 
 /**
- * <p>Configures and starts the asynchronous process of rotating the secret.</p>
+ * <p>Configures and starts the asynchronous process of rotating the secret. For more information about rotation,
+ *       see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html">Rotate secrets</a>.</p>
  *          <p>If you include the
  *       configuration parameters, the operation sets the values for the secret and then immediately
  *       starts a rotation. If you don't include the configuration parameters, the operation starts a
- *       rotation with the values already stored in the secret. For more information about rotation,
- *       see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html">Rotate secrets</a>.</p>
- *          <p>To configure rotation, you include the ARN of an Amazon Web Services Lambda function and the schedule
+ *       rotation with the values already stored in the secret. </p>
+ *          <p>For database credentials you want to rotate, for Secrets Manager to be able to rotate the secret, you must
+ *       make sure the secret value is in the
+ *         <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_secret_json_structure.html"> JSON structure
+ *         of a database secret</a>. In particular, if you want to use the <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets_strategies.html#rotating-secrets-two-users"> alternating users strategy</a>, your secret must contain the ARN of a superuser
+ *       secret.</p>
+ *
+ *          <p>To configure rotation, you also need the ARN of an Amazon Web Services Lambda function and the schedule
  *       for the rotation. The Lambda rotation function creates a new
  *       version of the secret and creates or updates the credentials on the database or service to
  *       match. After testing the new credentials, the function marks the new secret version with the staging
  *       label <code>AWSCURRENT</code>. Then anyone who retrieves the secret gets the new version. For more
  *       information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotate-secrets_how.html">How rotation works</a>.</p>
- *          <p>When rotation is successful, the <code>AWSPENDING</code> staging label might be attached to the same
- *       version as the <code>AWSCURRENT</code> version, or it might not be attached to any version.</p>
- *          <p>If the <code>AWSPENDING</code> staging label is present but not attached to the same version as
- *       <code>AWSCURRENT</code>, then any later invocation of <code>RotateSecret</code> assumes that a previous
- *       rotation request is still in progress and returns an error.</p>
+ *          <p>You can create the Lambda rotation function based on the <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_available-rotation-templates.html">rotation function templates</a> that Secrets Manager provides. Choose
+ *       a template that matches your <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets_strategies.html">Rotation strategy</a>.</p>
+ *          <p>When rotation is successful, the <code>AWSPENDING</code> staging label might be attached
+ *       to the same version as the <code>AWSCURRENT</code> version, or it might not be attached to any
+ *       version. If the <code>AWSPENDING</code> staging label is present but not attached to the same
+ *       version as <code>AWSCURRENT</code>, then any later invocation of <code>RotateSecret</code>
+ *       assumes that a previous rotation request is still in progress and returns an error.</p>
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:RotateSecret</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. You also need <code>lambda:InvokeFunction</code> permissions on the rotation function.
  *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets-required-permissions-function.html">

clients/client-secrets-manager/src/commands/RotateSecretCommand.ts

@@ -27,7 +27,7 @@ export interface StopReplicationToReplicaCommandOutput extends StopReplicationTo
  *          <p>
  *             <b>Required permissions: </b>
  *             <code>secretsmanager:StopReplicationToReplica</code>.
- *       For more information, see <a href="https://docs.aws.amazon.com/service-authorization/latest/reference/list_awssecretsmanager.html#awssecretsmanager-actions-as-permissions">
+ *       For more information, see <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html#reference_iam-permissions_actions">
  *       IAM policy actions for Secrets Manager</a> and <a href="https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html">Authentication
  *       and access control in Secrets Manager</a>. </p>
  * @example