DeleteSecret - AWS Secrets Manager

DeleteSecret

Deletes a secret and all of its versions. You can specify a recovery window during which you can restore the secret. The minimum recovery window is 7 days. The default recovery window is 30 days. Secrets Manager attaches a DeletionDate stamp to the secret that specifies the end of the recovery window. At the end of the recovery window, Secrets Manager deletes the secret permanently.

For information about deleting a secret in the console, see https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_delete-secret.html.

Secrets Manager performs the permanent secret deletion at the end of the waiting period as a background task with low priority. There is no guarantee of a specific time after the recovery window for the permanent delete to occur.

At any time before recovery window ends, you can use RestoreSecret to remove the DeletionDate and cancel the deletion of the secret.

In a secret scheduled for deletion, you cannot access the encrypted secret value. To access that information, first cancel the deletion with RestoreSecret and then retrieve the information.

Required permissions: secretsmanager:DeleteSecret. For more information, see IAM policy actions for Secrets Manager and Authentication and access control in Secrets Manager.

Request Syntax

{ "ForceDeleteWithoutRecovery": boolean, "RecoveryWindowInDays": number, "SecretId": "string" }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

ForceDeleteWithoutRecovery

Specifies whether to delete the secret without any recovery window. You can't use both this parameter and RecoveryWindowInDays in the same call. If you don't use either, then Secrets Manager defaults to a 30 day recovery window.

Secrets Manager performs the actual deletion with an asynchronous background process, so there might be a short delay before the secret is permanently deleted. If you delete a secret and then immediately create a secret with the same name, use appropriate back off and retry logic.

Important

Use this parameter with caution. This parameter causes the operation to skip the normal recovery window before the permanent deletion that Secrets Manager would normally impose with the RecoveryWindowInDays parameter. If you delete a secret with the ForceDeleteWithouRecovery parameter, then you have no opportunity to recover the secret. You lose the secret permanently.

Type: Boolean

Required: No

RecoveryWindowInDays

The number of days from 7 to 30 that Secrets Manager waits before permanently deleting the secret. You can't use both this parameter and ForceDeleteWithoutRecovery in the same call. If you don't use either, then Secrets Manager defaults to a 30 day recovery window.

Type: Long

Required: No

SecretId

The ARN or name of the secret to delete.

For an ARN, we recommend that you specify a complete ARN rather than a partial ARN.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Response Syntax

{ "ARN": "string", "DeletionDate": number, "Name": "string" }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

ARN

The ARN of the secret.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

DeletionDate

The date and time after which this secret Secrets Manager can permanently delete this secret, and it can no longer be restored. This value is the date and time of the delete request plus the number of days in RecoveryWindowInDays.

Type: Timestamp

Name

The name of the secret.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Errors

For information about the errors that are common to all actions, see Common Errors.

InternalServiceError

An error occurred on the server side.

HTTP Status Code: 500

InvalidParameterException

The parameter name is invalid value.

HTTP Status Code: 400

InvalidRequestException

A parameter value is not valid for the current state of the resource.

Possible causes:

  • The secret is scheduled for deletion.

  • You tried to enable rotation on a secret that doesn't already have a Lambda function ARN configured and you didn't include such an ARN as a parameter in this call.

HTTP Status Code: 400

ResourceNotFoundException

Secrets Manager can't find the resource that you asked for.

HTTP Status Code: 400

Examples

Example

The following example shows how to delete a secret with a recovery window of 7 days. The JSON request string input and response output displays formatted code with white space and line breaks for better readability. Submit your input as a single line JSON string.

Sample Request

POST / HTTP/1.1 Host: secretsmanager.region.domain Accept-Encoding: identity X-Amz-Target: secretsmanager.DeleteSecret Content-Type: application/x-amz-json-1.1 User-Agent: <user-agent-string> X-Amz-Date: <date> Authorization: AWS4-HMAC-SHA256 Credential=<credentials>,SignedHeaders=<headers>, Signature=<signature> Content-Length: <payload-size-bytes> { "SecretId": "MyTestDatabaseSecret", "RecoveryWindowInDays": 7 }

Sample Response

HTTP/1.1 200 OK Date: <date> Content-Type: application/x-amz-json-1.1 Content-Length: <response-size-bytes> Connection: keep-alive x-amzn-RequestId: <request-id-guid> { "ARN":"arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", "DeletionDate":1.524085349095E9, "Name":"MyTestDatabaseSecret" }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: