Stores a new encrypted secret value in the specified secret. To do this, the operation creates a new version and attaches it to the secret. The version can contain a new
value or a new
value. You can also specify the staging labels that are initially attached to the new version.
The Secrets Manager console uses only the
field. To add binary data to a secret with the
field you must use the AWS CLI or one of the AWS SDKs.
- If this operation creates the first version for the secret then Secrets Manager automatically attaches the staging label
AWSCURRENT to the new version.
- If another version of this secret already exists, then this operation does not automatically move any staging labels other than those that you explicitly specify in the
- If this operation moves the staging label
AWSCURRENT from another version to this version (because you included it in the
StagingLabels parameter) then Secrets Manager also automatically moves the staging label
AWSPREVIOUS to the version that
AWSCURRENT was removed from.
- This operation is idempotent. If a version with a
VersionId with the same value as the
ClientRequestToken parameter already exists and you specify the same secret data, the operation succeeds but does nothing. However, if the secret data is different, then the operation fails because you cannot modify an existing version; you can only create new ones.
- If you call an operation that needs to encrypt or decrypt the
SecretBinary for a secret in the same account as the calling user and that secret doesn't specify a AWS KMS encryption key, Secrets Manager uses the account's default AWS managed customer master key (CMK) with the alias
aws/secretsmanager. If this key doesn't already exist in your account then Secrets Manager creates it for you automatically. All users and roles in the same AWS account automatically have access to use the default CMK. Note that if an Secrets Manager API call results in AWS having to create the account's AWS-managed CMK, it can result in a one-time significant delay in returning the result.
- If the secret is in a different AWS account from the credentials calling an API that requires encryption or decryption of the secret value then you must create and use a custom AWS KMS CMK because you can't access the default CMK for the account using credentials from a different AWS account. Store the ARN of the CMK in the secret when you create the secret or when you update it by including it in the
KMSKeyId. If you call an API that must encrypt or decrypt
SecretBinary using credentials from a different account then the AWS KMS key policy must grant cross-account access to that other account's user or role for both the kms:GenerateDataKey and kms:Decrypt operations.
To run this command, you must have the following permissions:
- kms:GenerateDataKey - needed only if you use a customer-managed AWS KMS key to encrypt the secret. You do not need this permission to use the account's default AWS managed CMK for Secrets Manager.