Modify an AWS Secrets Manager secret

You can modify the metadata of a secret after it is created, depending on who created the secret. For secrets created by other services, you might need to use the other service to update or rotate it.

To determine who manages a secret, you can review the secret name. Secrets managed by other services are prefixed with the ID of that service. Or, in the AWS CLI, call describe-secret, and then review the field OwningService. For more information, see AWS Secrets Manager secrets managed by other AWS services.

For secrets you manage, you can modify the description, resource-based policy, the encryption key, and tags. You can also change the encrypted secret value; however, we recommend you use rotation to update secret values that contain credentials. Rotation updates both the secret in Secrets Manager and the credentials on the database or service. This keeps the secret automatically synchronized so when clients request a secret value, they always get a working set of credentials. For more information, see Rotate AWS Secrets Manager secrets.

To update a secret you manage (console)

1. Open the Secrets Manager console at https://console.aws.amazon.com/secretsmanager/.

2. From the list of secrets, choose your secret.

3. On the secret details page, do any of the following:

   Note that you can't change the name or ARN of a secret.

   • To update the description, in the Secrets details section, choose Actions, and then choose Edit description.

   • To update the encryption key, in the Secrets details section, choose Actions, and then choose Edit encryption key. See Secret encryption and decryption in AWS Secrets Manager.

   • To update tags, in the Tags section, choose Edit. See Tag AWS Secrets Manager secrets.

   • To update the secret value, in the Secret value section, choose Retrieve secret value and then choose Edit.

     Secrets Manager creates a new version of the secret with the staging label AWSCURRENT. You can still access the old version. From the CLI, use the get-secret-value action with version-id AWSPREVIOUS.

   • To update rotation for your secret, choose Edit rotation. See Rotate AWS Secrets Manager secrets.

   • To update permissions for your secret, choose Edit permissions. See Attach a permissions policy to an AWS Secrets Manager secret.

   • To replicate your secret to other Regions, see Replicate a secret to other Regions.

   • If your secret has replicas, you can change the encryption key for a replica. In the Replicate secret section, select the radio button for the replica, and then on the Actions menu, choose Edit encryption key. See Secret encryption and decryption in AWS Secrets Manager.

   • To change a secret so that it is managed by another service, you need to recreate the secret in that service. See Secrets managed by other services.

AWS CLI

Example Update secret description

The following update-secret example updates the description of a secret.

aws secretsmanager update-secret \
    --secret-id MyTestSecret \
    --description "This is a new description for the secret."

Example Update the encryption key associated with a secret

The following update-secret example updates the KMS key used to encrypt the secret value. The KMS key must be in the same region as the secret.

aws secretsmanager update-secret \
    --secret-id MyTestSecret \
    --kms-key-id arn:aws:kms:us-west-2:123456789012:key/EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE

Example Store a new secret value in a secret

When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. See Mitigate the risks of using the AWS CLI to store your AWS Secrets Manager secrets.

The following put-secret-value creates a new version of a secret with two key-value pairs.

aws secretsmanager put-secret-value \
    --secret-id MyTestSecret \
    --secret-string "{\"user\":\"diegor\",\"password\":\"EXAMPLE-PASSWORD\"}"

Example Store a new secret value from credentials in a JSON file

When you enter commands in a command shell, there is a risk of the command history being accessed or utilities having access to your command parameters. See Mitigate the risks of using the AWS CLI to store your AWS Secrets Manager secrets.

The following put-secret-value example creates a new version of a secret from credentials in a file. For more information, see Loading AWS CLI parameters from a file in the AWS CLI User Guide.

aws secretsmanager put-secret-value \
    --secret-id MyTestSecret \
    --secret-string file://mycreds.json

Contents of mycreds.json:

{
    "engine": "mysql",
    "username": "saanvis",
    "password": "EXAMPLE-PASSWORD",
    "host": "my-database-endpoint.us-west-2.rds.amazonaws.com",
    "dbname": "myDatabase",
    "port": "3306"
}

AWS SDK

We recommend you avoid calling PutSecretValue or UpdateSecret at a sustained rate of more than once every 10 minutes. When you call PutSecretValue or UpdateSecret to update the secret value, Secrets Manager creates a new version of the secret. Secrets Manager removes unlabeled versions when there are more than 100, but it does not remove versions created less than 24 hours ago. If you update the secret value more than once every 10 minutes, you create more versions than Secrets Manager removes, and you will reach the quota for secret versions.

To update a secret, use the following actions: UpdateSecret, ReplicateSecretToRegions, or PutSecretValue. For more information, see AWS SDKs.