# Manage secrets with AWS Secrets Manager
**Topics**
+ [Update a secret value](manage_update-secret-value.md)
+ [
# Generate a password with Secrets Manager
](generate-password.md)
+ [
# Roll back a secret to a previous version
](roll-back-secret.md)
+ [Change the encryption key for a secret](manage_update-encryption-key.md)
+ [Modify a secret](manage_update-secret.md)
+ [Find secrets](manage_search-secret.md)
+ [Delete a secret](manage_delete-secret.md)
+ [Restore a secret](manage_restore-secret.md)
+ [Tag secrets](managing-secrets_tagging.md)
# Update the value for an AWS Secrets Manager secret
To update the value of your secret, you can use the console, the CLI, or an SDK. When you update the secret value, Secrets Manager creates a new version of the secret with the staging label `AWSCURRENT`. You can still access the old version, which has the label `AWSPREVIOUS`. You can also add your own labels. For more information, see [Secrets Manager versioning](whats-in-a-secret.md#term_version).
**To update the secret value (console)**
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. From the list of secrets, choose your secret.
1. On the secret details page, on the **Overview** tab, in the **Secret value** section, choose **Retrieve secret value** and then choose **Edit**.
## AWS CLI
**To update the secret value (AWS CLI)**
+ 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](security_cli-exposure-risks.md).
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/put-secret-value.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/put-secret-value.html) 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\"}"
```
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/put-secret-value.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/put-secret-value.html) creates a new version with a custom staging label. The new version will have the labels `MyLabel` and `AWSCURRENT`.
```
aws secretsmanager put-secret-value \
--secret-id MyTestSecret \
--secret-string "{\"user\":\"diegor\",\"password\":\"EXAMPLE-PASSWORD\"}"
--version-stages "MyLabel"
```
## 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 value, use the following actions: [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html) or [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html). For more information, see [AWS SDKs](asm_access.md#asm-sdks).
# Generate a password with Secrets Manager
A common pattern for using Secrets Manager is to generate a password in Secrets Manager and then use that password in your database or service. You can do this using the following methods:
+ CloudFormation – See [Create AWS Secrets Manager secrets in AWS CloudFormation](cloudformation.md).
+ AWS CLI – See [https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-random-password.html](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-random-password.html).
+ AWS SDKs – See [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetRandomPassword.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetRandomPassword.html).
# Roll back a secret to a previous version
You can revert a secret to a previous version by moving the labels attached to secret versions using the AWS CLI. For information about how Secrets Manager stores versions of secrets, see [Secret versions](whats-in-a-secret.md#term_version).
The following [https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/update-secret-version-stage.html](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/update-secret-version-stage.html) example moves the AWSCURRENT staging label to the previous version of a secret, which reverts the secret to the previous version. To find the ID for the previous version, use [https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/list-secret-version-ids.html](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/list-secret-version-ids.html) or view the versions in the Secrets Manager console.
For this example, the version with the AWSCURRENT label is a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 and the version with the AWSPREVIOUS label is a1b2c3d4-5678-90ab-cdef-EXAMPLE22222. In this example, you move the AWSCURRENT label from version 11111 to 22222. Because the AWSCURRENT label is removed from a version, `update-secret-version-stage` automatically moves the AWSPREVIOUS label to that version (11111). The effect is that the AWSCURRENT and AWSPREVIOUS versions are swapped.
```
aws secretsmanager update-secret-version-stage \
--secret-id MyTestSecret \
--version-stage AWSCURRENT \
--move-to-version-id a1b2c3d4-5678-90ab-cdef-EXAMPLE22222 \
--remove-from-version-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
# Change the encryption key for an AWS Secrets Manager secret
Secrets Manager uses [envelope encryption](security-encryption.md) with AWS KMS keys and data keys to protect each secret value. For each secret, you can choose which KMS key to use. You can use the AWS managed key **aws/secretsmanager**, or you can use a customer managed key. For most cases, we recommend using **aws/secretsmanager**, and there is no cost for using it. If you need to access the secret from another AWS account, or if you want to use your own KMS key so that you can rotate it or apply a key policy to it, use a customer managed key. You must have [Permissions for the KMS key](security-encryption.md#security-encryption-authz). For information about the costs of using a customer managed key, see [Pricing](intro.md#asm_pricing).
You can change the encryption key for your secret. For example, if you want to [access the secret from another account](auth-and-access_examples_cross.md), and the secret is currently encrypted using the AWS managed key `aws/secretsmanager`, you can switch to a customer managed key.
**Tip**
If you want to rotate your customer managed key, we recommend using AWS KMS automatic key rotation. For more information, see [Rotating AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html).
When you change the encryption key, Secrets Manager re-encrypts `AWSCURRENT`, `AWSPENDING`, and `AWSPREVIOUS` versions with the new key. To avoid locking you out of the secret, Secrets Manager keeps all existing versions encrypted with the previous key. That means you can decrypt `AWSCURRENT`, `AWSPENDING`, and `AWSPREVIOUS` versions with the previous key or the new key. If you don't have `kms:Decrypt` permission to the previous key, when you change the encryption key, Secrets Manager can't decrypt the secret versions to re-encrypt them. In this case, the existing versions are not re-encrypted.
To make it so `AWSCURRENT` can only be decrypted by the new encryption key, create a new version of the secret with the new key. Then to be able to decrypt the `AWSCURRENT` secret version, you must have permission to the new key.
If you deactivate the previous encryption key, you will not be able to decrypt any secret versions except `AWSCURRENT`, `AWSPENDING`, and `AWSPREVIOUS`. If you have other labelled secret versions that you want to retain access to, you need to recreate those versions with the new encryption key using the [AWS CLI](#manage_update-encryption-key_CLI).
**To change the encryption key for a secret (console)**
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. From the list of secrets, choose your secret.
1. On the secret details page, in the **Secrets details** section, choose **Actions**, and then choose **Edit encryption key**.
## AWS CLI
If you change the encryption key for a secret and then deactivate the previous encryption key, you will not be able to decrypt any secret versions except `AWSCURRENT`, `AWSPENDING`, and `AWSPREVIOUS`. If you have other labelled secret versions that you want to retain access to, you need to recreate those versions with the new encryption key using the [AWS CLI](#manage_update-encryption-key_CLI).
**To change the encryption key for a secret (AWS CLI)**
1. The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/update-secret.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/update-secret.html) 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
```
1. (Optional) If you have secret versions that have custom labels, to re-encrypt them using the new key, you must recreate those versions.
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](security_cli-exposure-risks.md).
1. Get the value of the secret version.
```
aws secretsmanager get-secret-value \
--secret-id MyTestSecret \
--version-stage MyCustomLabel
```
Make a note of the secret value.
1. Create a new version with that value.
```
aws secretsmanager put-secret-value \
--secret-id testDescriptionUpdate \
--secret-string "SecretValue" \
--version-stages "MyCustomLabel"
```
# 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](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/describe-secret.html), and then review the field `OwningService`. For more information, see [AWS Secrets Manager secrets managed by other AWS services](service-linked-secrets.md).
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](rotating-secrets.md).
Secrets Manager generates a CloudTrail log entry when you modify a secret. For more information, see [Log AWS Secrets Manager events with AWS CloudTrail](monitoring-cloudtrail.md).
**To update a secret you manage (console)**
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. From the list of secrets, choose your secret.
1. 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, see [Change the encryption key for an AWS Secrets Manager secret](manage_update-encryption-key.md).
+ To update tags, on the **Tags** tab, choose **Edit tags**. See [Tagging secrets in AWS Secrets Manager](managing-secrets_tagging.md).
+ To update the secret value, see [Update the value for an AWS Secrets Manager secret](manage_update-secret-value.md).
+ To update permissions for your secret, on the **Overview** tab, choose **Edit permissions**. See [Resource-based policies](auth-and-access_resource-policies.md).
+ To update rotation for your secret, on the **Rotation** tab, choose **Edit rotation**. See [Rotate AWS Secrets Manager secrets](rotating-secrets.md).
+ To replicate your secret to other Regions, see [Multi-region replication](replicate-secrets.md).
+ If your secret has replicas, you can change the encryption key for a replica. On the **Replication** tab, 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](security-encryption.md).
+ 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](service-linked-secrets.md).
## AWS CLI
**Example Update secret description**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/update-secret.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/update-secret.html) example updates the description of a secret.
```
aws secretsmanager update-secret \
--secret-id MyTestSecret \
--description "This is a new description for the secret."
```
## 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: [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html) or [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ReplicateSecretToRegions.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ReplicateSecretToRegions.html). For more information, see [AWS SDKs](asm_access.md#asm-sdks).
# Find secrets in AWS Secrets Manager
When you search for secrets without a filter, Secrets Manager matches keywords in the secret name, description, tag key, and tag value. Searching without filters is not case-sensitive and ignores special characters, such as space, /, \$1, =, \$1, and only uses numbers and letters. When you search without a filter, Secrets Manager analyzes the search string to convert it to separate words. The words are separated by any change from uppercase to lowercase, from letter to number, or from number/letter to punctuation. For example, entering the search term `credsDatabase#892` searches for `creds`, `Database`, and `892` in name, description, and tag key and value.
Secrets Manager generates a CloudTrail log entry when you list secrets. For more information, see [Log AWS Secrets Manager events with AWS CloudTrail](monitoring-cloudtrail.md).
Secrets Manager is a regional service and only secrets within the selected region are returned.
## Search filters
If you don't use any filters, Secrets Manager breaks the search string into words and then searches all attributes for matches. This search is not case-sensitive. For example, searching for **My\$1Secret** matches secrets with the word **my** or **secret** in the name, description, or tags.
You can apply the following filters to your search:
**Name**
Matches the beginning of secret names; case-sensitive. For example, **Name:** **Data** returns a secret named `DatabaseSecret`, but not `databaseSecret` or `MyData`.
**Description**
Matches the words in secret descriptions, not case-sensitive. For example, **Description**: **My Description** matches secrets with the following descriptions:
+ `My Description`
+ `my description`
+ `My basic description`
+ `Description of my secret`
**Managed by**
Finds secrets managed by services outside of AWS, for example:
+ 1Password
+ Akeyless
+ CyberArk
+ HashiCorp
**Owning service**
Matches the beginning of the managing service ID prefix, not case-sensitive. For example, **my-ser** matches secrets managed by services with the prefix `my-serv` and `my-service`. For more information, see [Secrets managed by other services](service-linked-secrets.md).
**Replicated secrets**
You can filter for primary secrets, replica secrets, or secrets that aren't replicated.
**Tag keys**
Matches the beginning of tag keys; case-sensitive. For example, **Tag key:** **Prod** returns secrets with the tag `Production` and `Prod1`, but not secrets with the tag `prod` or `1 Prod`.
**Tag values**
Matches the beginning of tag values; case-sensitive. For example, **Tag value:** **Prod** returns secrets with the tag `Production` and `Prod1`, but not secrets with the tag value `prod` or `1 Prod`.
## AWS CLI
**Example List the secrets in your account**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/list-secrets.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/list-secrets.html) example gets a list of the secrets in your account.
```
aws secretsmanager list-secrets
```
**Example Filter the list of secrets in your account**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/list-secrets.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/list-secrets.html) example gets a list of the secrets in your account that have **Test** in the name. Filtering by name is case sensitive.
```
aws secretsmanager list-secrets \
--filters Key="name",Values="Test"
```
**Example Find secrets that are managed by other AWS services**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/list-secrets.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/list-secrets.html) example gets a list of secrets managed by a service. You specify the service by ID. For more information, see [Secrets managed by other services](service-linked-secrets.md).
```
aws secretsmanager list-secrets \
--filters Key="owning-service",Values=""
```
## AWS SDK
To find secrets by using one of the AWS SDKs, use [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ListSecrets.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ListSecrets.html). For more information, see [AWS SDKs](asm_access.md#asm-sdks).
# Delete an AWS Secrets Manager secret
Because of the critical nature of secrets, AWS Secrets Manager intentionally makes deleting a secret difficult. Secrets Manager does not immediately delete secrets. Instead, Secrets Manager immediately makes the secrets inaccessible and scheduled for deletion after a recovery window of a minimum of seven days. Until the recovery window ends, you can recover a secret you previously deleted. There is no charge for secrets that you have marked for deletion.
You can't delete a primary secret if it is replicated to other Regions. First delete the replicas, then delete the primary secret. When you delete a replica, it is deleted immediately.
You can't directly delete a version of a secret. Instead, you remove all staging labels from the version using the AWS CLI or AWS SDK. This marks the version as deprecated, and then Secrets Manager can automatically delete the version in the background.
If you don't know whether an application still uses a secret, you can create an Amazon CloudWatch alarm to alert you to any attempts to access a secret during the recovery window. For more information, see [Monitor when AWS Secrets Manager secrets scheduled for deletion are accessed](monitoring_cloudwatch_deleted-secrets.md).
To delete a secret, you must have `secretsmanager:ListSecrets` and `secretsmanager:DeleteSecret` permissions.
Secrets Manager generates a CloudTrail log entry when you delete a secret. For more information, see [Log AWS Secrets Manager events with AWS CloudTrail](monitoring-cloudtrail.md).
**To delete a secret (console)**
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. In the list of secrets, choose the secret you want to delete.
1. In the **Secret details** section, choose **Actions**, and then choose **Delete secret**.
1. In the **Disable secret and schedule deletion** dialog box, in **Waiting period**, enter the number of days to wait before the deletion becomes permanent. Secrets Manager attaches a field called `DeletionDate` and sets the field to the current date and time, plus the number of days specified for the recovery window.
1. Choose **Schedule deletion**.
**To view deleted secrets**
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. On the **Secrets** page, choose **Preferences** (![\[Gear icon representing settings or configuration options.\]](http://docs.aws.amazon.com/secretsmanager/latest/userguide/images/preferences-gear.png)).
1. In the Preferences dialog box, select **Show secrets scheduled for deletion**, and then choose **Save**.
**To delete a replica secret**
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. Choose the primary secret.
1. In the **Replicate Secret** section, choose the replica secret.
1. From the **Actions** menu, choose **Delete Replica**.
## AWS CLI
**Example Delete a secret**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/delete-secret.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/delete-secret.html) example deletes a secret. You can recover the secret with [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/restore-secret.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/restore-secret.html) until the date and time in the DeletionDate response field. To delete a secret that is replicated to other regions, first remove its replicas with [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/remove-regions-from-replication.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/remove-regions-from-replication.html), and then call [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/delete-secret.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/delete-secret.html).
```
aws secretsmanager delete-secret \
--secret-id MyTestSecret \
--recovery-window-in-days 7
```
**Example Delete a secret immediately**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/delete-secret.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/delete-secret.html) example deletes a secret immediately without a recovery window. You can't recover this secret.
```
aws secretsmanager delete-secret \
--secret-id MyTestSecret \
--force-delete-without-recovery
```
**Example Delete a replica secret**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/remove-regions-from-replication.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/remove-regions-from-replication.html) example deletes a replica secret in eu-west-3. To delete a primary secret that is replicated to other regions, first delete the replicas and then call [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/delete-secret.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/delete-secret.html).
```
aws secretsmanager remove-regions-from-replication \
--secret-id MyTestSecret \
--remove-replica-regions eu-west-3
```
## AWS SDK
To delete a secret, use the [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DeleteSecret.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DeleteSecret.html) command. To delete a version of a secret, use the [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecretVersionStage.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecretVersionStage.html) command. To delete a replica, use the [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_StopReplicationToReplica.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_StopReplicationToReplica.html) command. For more information, see [AWS SDKs](asm_access.md#asm-sdks).
# Restore an AWS Secrets Manager secret
Secrets Manager considers a secret scheduled for deletion *deprecated* and you can no longer directly access it. After the recovery window has passed, Secrets Manager deletes the secret permanently. Once Secrets Manager deletes the secret, you can't recover it. Before the end of the recovery window, you can recover the secret and make it accessible again. This removes the `DeletionDate` field, which cancels the scheduled permanent deletion.
To restore a secret and the metadata in the console, you must have `secretsmanager:ListSecrets` and `secretsmanager:RestoreSecret` permissions.
Secrets Manager generates a CloudTrail log entry when you restore a secret. For more information, see [Log AWS Secrets Manager events with AWS CloudTrail](monitoring-cloudtrail.md).
**To restore a secret (console)**
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. In the list of secrets, choose the secret you want to restore.
If deleted secrets don't appear in your list of secrets, choose **Preferences** (![\[Gear icon representing settings or configuration options.\]](http://docs.aws.amazon.com/secretsmanager/latest/userguide/images/preferences-gear.png)). In the Preferences dialog box, select **Show secrets scheduled for deletion**, and then choose **Save**.
1. On the **Secret details** page, choose **Cancel deletion**.
1. In the **Cancel secret deletion** dialog box, choose **Cancel deletion**.
## AWS CLI
**Example Restore a previously deleted secret**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/restore-secret.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/restore-secret.html) example restores a secret that was previously scheduled for deletion.
```
aws secretsmanager restore-secret \
--secret-id MyTestSecret
```
## AWS SDK
To restore a secret marked for deletion, use the [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_RestoreSecret.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_RestoreSecret.html) command. For more information, see [AWS SDKs](asm_access.md#asm-sdks).
# Tagging secrets in AWS Secrets Manager
In AWS Secrets Manager, you can assign metadata to your secrets using tags. A tag is a key-value pair that you define for a secret. Tags help you manage AWS resources and organize data, including billing information.
With tags, you can:
+ Manage, search, and filter secrets and other resources in your AWS account
+ Control access to secrets based on attached tags
+ Track and categorize expenses associated with specific secrets or projects
For more information about using tags to control access, see [Control access to secrets using attribute-based access control (ABAC)](auth-and-access-abac.md).
To learn about cost allocation tags, see [Using AWS cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the AWS Billing User Guide.
For information about tag quotas and naming restrictions, see [Service quotas for Tagging](https://docs.aws.amazon.com/general/latest/gr/arg.html#taged-reference-quotas) in the *AWS General Reference guide*. Tags are case-sensitive.
Secrets Manager generates a CloudTrail log entry when you tag or untag a secret. For more information, see [Log AWS Secrets Manager events with AWS CloudTrail](monitoring-cloudtrail.md).
**Tip**
Use a consistent tagging scheme across all your AWS resources. For best practices, see the [Tagging Best Practices](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html) whitepaper.
## Review tag basics
You can find secrets by tags in the console, AWS CLI, and SDKs. AWS also provides the [Resource Groups](https://docs.aws.amazon.com/ARG/latest/userguide/resource-groups.html) tool to create a custom console that consolidates and organizes your resources based on their tags. To find secrets with a specific tag, see [Find secrets in AWS Secrets Manager](manage_search-secret.md).
You can use the Secrets Manager console, AWS CLI, or Secrets Manager API to:
+ Create a secret with tags
+ Add tags to a secret
+ List the tags for your secrets
+ Remove tags from a secret
You can use tags to categorize your secrets. For example, you can categorize secrets by purpose, owner, or environment. Because you define the key and value for each tag, you can create a custom set of categories to meet your specific needs. Here are several examples of tags:
+ `Project: Project name`
+ `Owner: Name`
+ `Purpose: Load testing`
+ `Application: Application name`
+ `Environment: Production`
## Track costs using tagging
You can use tags to categorize and track your AWS costs. When you apply tags to your AWS resources, including secrets, your AWS cost allocation report includes usage and costs aggregated by tags. You can apply tags that represent business categories (such as cost centers, application names, or owners) to organize your costs across multiple services. For more information, see [Use Cost Allocation Tags for Custom Billing Reports](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the *AWS Billing User Guide*.
## Understand tag restrictions
The following restrictions apply to tags.
**Basic restrictions**
+ The maximum number of tags per resource (secret) is 50.
+ Tag keys and values are case-sensitive.
+ You can't change or edit tags for a deleted secret.
**Tag key restrictions**
+ Each tag key must be unique. If you add a tag with a key that's already in use, your new tag overwrites the existing key-value pair.
+ You can't start a tag key with `aws:` because this prefix is reserved for use by AWS. AWS creates tags that begin with this prefix on your behalf, but you can't edit or delete them.
+ Tag keys must be between 1 and 128 Unicode characters in length.
+ Tag keys must consist of the following characters: Unicode letters, digits, white space, and the following special characters: `_ . / = + - @`.
**Tag value restrictions**
+ Tag values must be between 0 and 255 Unicode characters in length.
+ Tag values can be blank. Otherwise, they must consist of the following characters: Unicode letters, digits, white space, and any of the following special characters: `_ . / = + - @`.
## Tag secrets using the Secrets Manager console
You can manage tags for your secrets using the [Secrets Manager console](https://console.aws.amazon.com/secretsmanager).
To access the tagging features, do the following:
1. Open the Secrets Manager console.
1. In the navigation bar, choose your preferred Region.
1. On the **Secrets** page, select a secret.
**To view the tags for a secret**
+ On the **Secret Details** page, choose the **Tags** tab.
**To create a secret with a tag**
+ Follow the steps in [Create secrets](create_secret.md).
**To add or edit tags for a secret**
1. On the **Secret Details** page, choose the **Tags** tab and then choose **Edit tags**.
1. Enter the tag key in the **Key** field. Optionally, enter a tag value in the **Value** field.
1. Choose **Save**. The new or updated tag appears in the list of tags.
**Note**
If the **Save** button is not enabled, the tag key or value might not meet the tag restrictions. For more information, see [Understand tag restrictions](#tagging-restrictions).
**To remove a tag from a secret**
1. On the **Secret details** page, choose the **Tags** tab, and then choose the **Remove** icon next to the tag you want to remove.
1. Choose **Save** to confirm the removal, or select **Undo** to cancel.
## Tag secrets using the AWS CLI
### AWS CLI examples
**Example Add a tag to a secret**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/tag-resource.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/tag-resource.html) example shows how to attach a tag with shorthand syntax.
```
aws secretsmanager tag-resource \
--secret-id MyTestSecret \
--tags Key=FirstTag,Value=FirstValue
```
**Example Add multiple tags to a secret**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/tag-resource.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/tag-resource.html) example attaches two key-value tags to a secret.
```
aws secretsmanager tag-resource \
--secret-id MyTestSecret \
--tags '[{"Key": "FirstTag", "Value": "FirstValue"}, {"Key": "SecondTag", "Value": "SecondValue"}]'
```
**Example Remove tags from a secret**
The following [https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/untag-resource.html](https://docs.aws.amazon.com//cli/latest/reference/secretsmanager/untag-resource.html) example removes two tags from a secret. For each tag, both key and value are removed.
```
aws secretsmanager untag-resource \
--secret-id MyTestSecret \
--tag-keys '[ "FirstTag", "SecondTag"]'
```
## Tag secrets using the Secrets Manager API
You can add, list, and remove tags using the Secrets Manager API. For examples, see the following documentation:
+ [ListSecrets](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ListSecrets.html): Use `ListSecrets` to view the tags applied to a secret
+ [TagResource](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_TagResource.html): Add tags to a secret
+ [Untag](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UntagResource.html): Remove tags from a secret
## Tag secrets using the Secrets Manager AWS SDK
To change tags for your secret, use the following API operations:
+ [ListSecrets](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_ListSecrets.html): Use `ListSecrets` to view the tags applied to a secret
+ [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_TagResource.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_TagResource.html): Add tags to a secret
+ [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UntagResource.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UntagResource.html): Remove tags from a secret
For more information about using the SDK, see [AWS SDKs](asm_access.md#asm-sdks).