21 Examples to Manage Secrets using AWS Secrets Manager CLI

by Ramesh Natarajan on March 15, 2022

Using AWS Secrets manager you can store, retrieve, rotate and manage secrets such as database credentials, API keys and other sensitive information used by your application.

Secrets are rotated without any disruption to your application, and you can also replicate secrets to multiple AWS regions.

You can manage secrets from AWS console, SDK, CLI, or CloudFormation. This tutorial explains how to perform the following essential secrets manager activities using AWS secretsmanager CLI:

List all Secrets
Create a PlainText Secret
Retrieve an Existing Secret Value
View details of an Existing Secret
Delete a Secret
Modify Details of an Existing Secret
Create a Secret and attach Tags
Create Key/Value Pair Secret from a JSON file
Create a Secret and Encrypt with KMS Key ID
List All Versions of an Existing Secret
Retrieve Previous Version of the Secret
Retrieve an Existing Secret Value using Version Id
Update/Store a New Encrypted Secret Value for an Existing Secret
Update/Store a New Encrypted Secret Value for an Existing Secret along with given Version Stage
Update/Store a New Key/Value Pair from a JSON file for an Existing Secret
Delete a Secret After x Number of Days
Force Delete a Secret Immediately
Cancel the Scheduled Deletion of a Secret
Add Tag Values to an Existing Secret
Remove Tags from an Existing Secret
Create a Staging Label to Specific Version of a Secret

1. List all Secrets using list-secrets

First, to view all current secrets in your AWS Secrets Manager, execute the following command.

$ aws secretsmanager list-secrets
{
  "SecretList": [
    {
      "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
      "Name": "ramesh",
      "LastChangedDate": "2022-03-10T17:56:17.027000-07:00",
      "LastAccessedDate": "2022-03-10T17:00:00-07:00",
      "SecretVersionsToStages": {
          "11111111-7777-41aa-b11c-be111111111d": [
              "AWSPREVIOUS"
          ],
          "22222222-8888-51cc-d55e-jk222222222f": [
              "AWSCURRENT"
          ]
      }
    }
  ]
}

The above output will display the ARN of the secret, secret name, date when secret was created and last accessed, the version-number of current and previous version of the secret along with their staging labels.

If you are new to AWS CLI, make sure your AWS profile is setup properly with appropriate access key. Refer to this for more detail: 15 AWS Configure Command Examples to Manage Multiple Profiles for CLI

2. Create a PlainText Secret using create-secret

The following examples creates a new secret. The secret data to be encrypted can either be a text or binary data. If you are using text, use the SecretString parameter as shown below. For binary data, use SecretBinary parameter. When you create secrets for the first time, Secrets Manager also creates an initial version and automatically attaches the staging label AWSCURRENT to the this new version.

$ aws secretsmanager create-secret --name jason \
    --description "This is the password for dev-db admin user1" \
    --secret-string "MySecretSecureString$123"
{
    "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:jason-ajajf1",
    "Name": "jason",
    "VersionId": "11111111-595c-aaaa-806a-222222222222"
}

In the above example, you’ll provide the name of your secret, a description, and the secret-string value. Once a secert is created, the output will display the ARN of the secret along with the VersionId.

To create a new secret, you need secretsmanager:CreateSecret permission.

3. Retrieve an Existing Secret Value using get-secret-value

To retrieve the secret value of an existing secret, execute the following command. This will retrieve the secret value either from the encryption field SecretString or SecretBinary whichever contains content.

To execute this command, you should have secretsmanager:GetSecretValue permission. If the secret key is encrypted with customer-managed KMS key, you also need kms:Decrypt permission.

$ aws secretsmanager get-secret-value --secret-id ramesh
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "VersionId": "22222222-8888-51cc-d55e-jk222222222f",
  "SecretString": "MySecure^Pass123",
  "VersionStages": [
      "AWSCURRENT"
  ],
  "CreatedDate": "2022-03-10T17:56:17.021000-07:00"
}

As you see from the above output, this secret is associated with AWSCURRENT version. Secrets Manager stores the encrypted secret data in one of a collection of versions associated with the secret. Each version has a copy of the encrypted secret data and is associated with one or more staging labels.

4. View details of an Existing Secret using describe-secret

This command will provided details about the secret without displaying the value of the secret itself. As you see in the following output, this displays the name, ARN, version details and few other date fields about the secret. You also need secretsmanager:DescribeSecret permission to execute this command.

$ aws secretsmanager describe-secret --secret-id ramesh
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "LastChangedDate": "2022-03-10T17:56:17.027000-07:00",
  "LastAccessedDate": "2022-03-10T17:00:00-07:00",
  "VersionIdsToStages": {
      "11111111-7777-41aa-b11c-be111111111d": [
          "AWSPREVIOUS"
      ],
      "22222222-8888-51cc-d55e-jk222222222f": [
          "AWSCURRENT"
      ]
  }
}

5. Delete a Secret using delete-secret

You can delete an existing secret as shown below. Once it’s deleted, list-secrets will not show this secrets anymore.

$ aws secretsmanager delete-secret --secret-id ramesh
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "DeletionDate": "2022-03-09T18:03:39.604000-07:00"
}

$ aws secretsmanager list-secrets
{
  "SecretList": []
}

If you’ve deleted a secret by mistake, you still have the option to recover it within 30 days. If you do a describe-secret on the deleted secret, you’ll see “DeletedDate” field, which indicates the end of the recovery window. Once the recovery window is over, the secret will be permanently deleted.

$ aws secretsmanager describe-secret --secret-id ramesh
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "Description": "This is the password for dev-db admin user",
  "LastChangedDate": "2022-03-10T18:03:39.625000-07:00",
  "LastAccessedDate": "2022-03-10T17:00:00-07:00",
  "DeletedDate": "2022-03-10T18:03:39.615000-07:00",
  "VersionIdsToStages": {
      "11111111-7777-41aa-b11c-be111111111d": [
          "AWSPREVIOUS"
      ],
      "22222222-8888-51cc-d55e-jk222222222f": [
          "AWSCURRENT"
      ]
  }
}

Note: You can also change the recovery window or delete the secret without recovery as explained in couple of examples below.

6. Modify Details of an Existing Secret using update-secret

Note: If you include a ClientRequestToken and either SecretString or SecretBinary then it also creates a new version attached to the secret.

Use update-secrets to update several details of the given secret. For example, the following will update only the description field of the secret. Please note that to execute this command, you should have secretsmanager:UpdateSecret permission.

$ aws secretsmanager update-secret --secret-id ramesh \
    --description "This is the password for dev-db admin user"
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh"
}

If you want to change only the secret value, use the following command and provide the new value of the secret.

$ aws secretsmanager update-secret --secret-id ramesh \
    --secret-string "NewlyUpdatedSecret#"
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "VersionId": "11111111-abcd-efgh-3786-bbbbbbbbbbbb"
}

You can also change more than one field of the secret using the same update command. The following example changes both the secret value and the KMS keyId associated with a secret.

$ aws secretsmanager update-secret --secret-id john \
    --secret-string "NewlyUpdatedSecret#"\
    --kms-key-id 45454545-3f66-4848-afaf-a8a8a8a8a8a8
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:john-tstsPn",
  "Name": "john",
  "VersionId": "11111111-f34c-4d4d-b8b8-222222222222"
}

If you use a custom AWS KMS key to encrypt the secret, you also need these two permissions:, kms:GenerateDataKey, kms:Decrypt

7. Create a Secret and attach Tags to it using create-secret

When creating a new secret, you can attach a tag at the same time using the –tags option as shown below. In this example, it attaches a Tag with key name “Environment” and its value as “Development”

$ aws secretsmanager create-secret --name ramesh3 \
    --description "This is the password for dev-db admin user1" \
    --secret-string "MySecretSecureString$123" \
    --tags "Key=Environment,Value=Development"
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh3-nunuBa",
  "Name": "ramesh3",
  "VersionId": "11111111-c4c4-4128-8989-222222222222"
}

8. Create Key/Value Pair Secret from a JSON file using create-secret

You can also create a Key/Value pair secret from a JSON file as shown below. In this example, there are two Key/Value pairs in the JSON file.

$ aws secretsmanager create-secret --name ramesh2 \
    --description "This is key value pair username and password JSON" \
    --secret-string file://secretvalues.json
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh2-ababED",
  "Name": "ramesh2",
  "VersionId": "11111111-0606-4c59-b460-222222222222"
}

$ cat secretvalues.json
{
  "UserId": "ramesh",
  "Password": "MySuperSecretPassword"
}

Note: The above will be store as “Secret key/value” in the secret with two “Secret Key” and it’s corresponding “Secret Value”

9. Create a Secret and Encrypt with KMS Key ID using create-secret

While creating a new secret, you can also encrypt it using KMS key by providing one of these: ARN, Key ID, or alias of the AWS KMS customer master key (CMK) to be used to encrypt the SecretString or SecretBinary values in the versions stored in this secret.

The following example creates a new secret and encrypts it using the given KMS key id:

$ aws secretsmanager create-secret --name ramesh4 \
    --description "This is the password for dev-db admin user1" \
    --secret-string "MySecretSecureString$123" \
    --kms-key-id 45454545-3f66-4848-afaf-a8a8a8a8a8a8
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh4-vavaKy",
  "Name": "ramesh4",
  "VersionId": "11111111-8686-4025-957a-222222222222"
}

If you don’t specify a KMS key id parameter, Secrets Manager uses the default AWS managed CMK aws/secretsmanager . If it doesn’t exist in your account, it will be created automatically the first time it encrypts the secret value.

10. List All Versions of an Existing Secret using list-secret-version-ids

The following command will list all the versions attached to the given secret. This will display only those versions that have atleast one label in VersionStage attached. As you see from the following output, part from displaying AWSCURRENT and AWSPREVIOUS stages, it also shows the custom Development version that is associated with this secret.

$ aws secretsmanager list-secret-version-ids --secret-id ramesh
{
  "Versions": [
    {
        "VersionId": "11111111-abcd-efgh-3786-bbbbbbbbbbbb",
        "VersionStages": [
            "AWSCURRENT"
        ],
        "LastAccessedDate": "2022-03-10T17:00:00-07:00",
        "CreatedDate": "2022-03-10T13:13:44.121000-07:00"
    },
    {
        "VersionId": "22222222-8888-51cc-d55e-jk222222222f",
        "VersionStages": [
            "AWSPREVIOUS"
        ],
        "LastAccessedDate": "2022-03-10T17:00:00-07:00",
        "CreatedDate": "2022-03-10T17:56:17.021000-07:00"
    },
    {
        "VersionId": "22222222-abcd-efgh-3786-eeeeeeeeeeee",
        "VersionStages": [
            "Development"
        ],
        "CreatedDate": "2022-03-10T10:38:58.325000-07:00"
    }
  ],
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh"
}

You need secretsmanager:ListSecretVersionIds permission to execute the above command.

11. Retrieve Previous Version of the Secret using get-secret-value Version Stage

Once you’ve updated the value of the secret. If you like to know the previous value before the update, you can use AWSPREVIOUS version stage as shown below.

$ aws secretsmanager get-secret-value --secret-id ramesh --version-stage AWSPREVIOUS
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "VersionId": "11111111-7777-41aa-b11c-be111111111d",
  "SecretString": "MySec^Pass124",
  "VersionStages": [
      "AWSPREVIOUS"
  ],
  "CreatedDate": "2022-03-10T17:54:56.259000-07:00"
}

As you see below the SecretString value for AWSCURRENT is different than the above AWSCURRENT value.

$ aws secretsmanager get-secret-value --secret-id ramesh --version-stage AWSCURRENT
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "VersionId": "22222222-8888-51cc-d55e-jk222222222f",
  "SecretString": "MySecure^Pass123",
  "VersionStages": [
      "AWSCURRENT"
  ],
  "CreatedDate": "2022-03-10T17:56:17.021000-07:00"
}

12. Retrieve an Existing Secret Value using Version Id

Instead of using the AWSCURRENT or AWSCURRENT version stage, you can also use the version-id to retrieve the corresponding SecretValue as shown below.

$ aws secretsmanager get-secret-value --secret-id ramesh --version-id 22222222-8888-51cc-d55e-jk222222222f
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "VersionId": "22222222-8888-51cc-d55e-jk222222222f",
  "SecretString": "MySecure^Pass123",
  "VersionStages": [
      "AWSPREVIOUS"
  ],
  "CreatedDate": "2022-03-10T17:56:17.021000-07:00"
}

To get all the version ids of a secret use describe-secret as shown in one of the examples above.

13. Update/Store a New Encrypted Secret Value for an Existing secret-id using put-secret-value

To update a secret value, use put-secret-value as shown below. This will store the given new secret value in the specified secret. For this, it will create a new version of the secret. To execute this command, you also need secretsmanager:PutSecretValue permission.

The following are few essential things to keep in mind:

If this is the first version of the secret, then secret manager will automatically assign AWSCURRENT as the staging label to this version.
If another version of the secret already exists, then secret manager does not any staging labels automatically other than those specified in the VersionStages parameter.
If another version of the secret already exists, and if you are moving the AWSCURRENT staging label by explicitly using the StagingLabels parameter, then secrets manager will also move AWSPREVIOUS staging label to the specific version where AWSCURRENT was removed

$ aws secretsmanager put-secret-value --secret-id ramesh \
  --secret-string "MySec^Pass124"
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "VersionId": "11111111-9b98-4cc7-ab83-333333333333",
  "VersionStages": [
      "AWSCURRENT"
  ]
}

14. Update/Store a New Encrypted Secret Value for an Existing secret-id using put-secret-value Version Stages

The following example shows how you can use version-stages parameter along with put-secret-values. In this example, a new version of the secret is created with the given value in secret-string and “Development” staging label is assigned to this particular version.

$ aws secretsmanager put-secret-value --secret-id ramesh \
  --secret-string "MySec^Pass124"\
  --version-stages "Development"

As you see from the following output, Development staging label is shown in the “VersionIdsToStages” along with AWSCURRENT and AWSPREVIOUS.

$ aws secretsmanager describe-secret --secret-id ramesh
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "Description": "This is the password for dev-db admin user",
  "RotationEnabled": false,
  ..
  ..
  "VersionIdsToStages": {
      "11111111-abcd-efgh-3786-bbbbbbbbbbbb": [
          "AWSCURRENT"
      ],
      "22222222-abcd-efgh-3786-eeeeeeeeeeee": [
          "Development"
      ],
      "22222222-8888-51cc-d55e-jk222222222f": [
          "AWSPREVIOUS"
      ]
  }
}

15. Update/Store a New Key/Value Pair from a JSON file for an Existing secret-id using put-secret-value

Instead of specifying the secret value directly in the command line, you can add the secret value in a json file, and pass that json file to the secret-string parameter as shown below.

$ aws secretsmanager put-secret-value --secret-id john \
     --secret-string file://secretvalues.json
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:john-tstsPn",
  "Name": "john",
  "VersionId": "55555555-cfb4-455a-8f71-888888888888",
  "VersionStages": [
      "AWSCURRENT"
  ]
}

16. Delete a Secret After x Number of Days using delete-secret

By default deleted secrets has a recovery window of 30 days and beyond that they are permanently deleted. If you like to change the recovery window, use the recovery-window-in-days option as shown below.

$ aws secretsmanager delete-secret --secret-id john --recovery-window-in-days 21
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:john-tstsPn",
  "Name": "john",
  "DeletionDate": "2022-03-10T11:05:24.533000-07:00"
}

Valid values should be between 7 and 30 days. If you specify a value outside that range, you’ll get this error message: An error occurred (InvalidParameterException) when calling the DeleteSecret operation: The RecoveryWindowInDays value must be between 7 and 30 days (inclusive).

17. Force Delete a Secret Immediately using delete-secret

You can also forcefully delete the secret immediately using force-delete-without-recovery option as shown below. Be careful when using this option as this will permanently delete the secret immediately.

$ aws secretsmanager delete-secret --secret-id john --force-delete-without-recovery
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:john-tstsPn",
  "Name": "john",
  "DeletionDate": "2022-03-10T11:02:29.554000-07:00"
}

18. Cancel the Scheduled Deletion of a Secret using restore-secret

If you’ve deleted a secret by mistake, or if you’ve changed your mind and like to restore the secret within the recovery window, use the restore-secret option as shown below. This will cancel the scheduled deletion of the secret and will remove the DeletedDate timestamp from it.

$ aws secretsmanager restore-secret --secret-id ramesh
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh"
}

Once you restore a secret, you can query it using list-secrets or describe-secret command.

$ aws secretsmanager list-secrets
{
  "SecretList": [
    {
      "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
      "Name": "ramesh",
      "Description": "This is the password for dev-db admin user",
      ..
      ..
}

$ aws secretsmanager describe-secret --secret-id ramesh
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  "Description": "This is the password for dev-db admin user",
  ..
  ..
}

19. Add Tag Values to an Existing Secret using tag-resource

You can add tags to an existing secret using tag-resoure option as shown below. You can add one or more tags by passing an array to the tags parameter. In the following example, two tags are added to the given secret. The tags are passed as key-value pair.

$ aws secretsmanager tag-resource --secret-id ramesh \
  --tags '[{"Key": "Name", "Value": "Ramesh"}, {"Key": "Environment", "Value": "Dev"}]'

As you see from the following output, both Environment and Name tags are added to this secret.

$ aws secretsmanager describe-secret --secret-id ramesh
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh",
  ..
  ..

  "Tags": [
    {
        "Key": "Environment",
        "Value": "Dev"
    },
    {
        "Key": "Name",
        "Value": "Ramesh"
    }
  ],
  ..
  ..
}

20. Remove Tags from an Existing Secret using untag-resource

You can remove one or more tags from a secret using untag-resource option. To remove a tag from the given secret, you have to pass only the key name of the secret.

The following example will remove both Name and Environment tags along with its value from the given secret.

aws secretsmanager untag-resource --secret-id ramesh \
--tag-keys '[ "Environment", "Name"]'

21. Create a Staging Label to Specific Version of a Secret using update-secret-version-stage

The following secret currently has three different versions with AWSCURRENT, AWSPREVIOUS and Development as staging labels.

$ aws secretsmanager list-secret-version-ids --secret-id ramesh
{
  "Versions": [
    {
        "VersionId": "11111111-abcd-efgh-3786-bbbbbbbbbbbb",
        "VersionStages": [
            "AWSCURRENT"
        ],
        ..
    },
    {
        "VersionId": "22222222-8888-51cc-d55e-jk222222222f",
        "VersionStages": [
            "AWSPREVIOUS"
        ],
        ..
    },
    {
        "VersionId": "22222222-abcd-efgh-3786-eeeeeeeeeeee",
        "VersionStages": [
            "Development"
        ],
        ..
    }
  ],
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh"
}

You can change the staging label associated with a specific version of a secret using update-secret-version-stage option as shown below. In this example the staging label DEVDB-UPGRADE will be added to the specific version of the given secret id.

$ aws secretsmanager update-secret-version-stage --secret-id ramesh \
  --version-stage DEVDB-UPGRADE \
  --move-to-version-id 22222222-8888-51cc-d55e-jk222222222f
{
  "ARN": "arn:aws:secretsmanager:us-east-1:111111111111:secret:ramesh-aaabbb",
  "Name": "ramesh"
}

As you see below, DEVDB-UPGRADE was added to that particular version along with the staging label AWSPREVIOUS that was already present for that particular version.

$ aws secretsmanager list-secret-version-ids --secret-id ramesh
{
  "Versions": [
    ..
    ..
    {
      "VersionId": "22222222-8888-51cc-d55e-jk222222222f",
      "VersionStages": [
          "DEVDB-UPGRADE",
          "AWSPREVIOUS"
      ],
  ..
}

If you want to remove a specifiv staging label from a version, use update-secret-version-stage and remove-from-version-id as shown below. This will remove DEVDB-UPGRADE staging label from the specified verion of the secret.

aws secretsmanager update-secret-version-stage --secret-id ramesh \
    --version-stage DEVDB-UPGRADE \
    --remove-from-version-id 22222222-8888-51cc-d55e-jk222222222f

Add your comment