Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

PutSecretValue

Creates a new version with a new encrypted secret value and attaches it to the secret. The version can contain a new SecretString value or a new SecretBinary value.

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

You can specify the staging labels to attach to the new version in VersionStages. If you don't include VersionStages, then Secrets Manager automatically moves the staging label AWSCURRENT to this version. If this operation creates the first version for the secret, then Secrets Manager automatically attaches the staging label AWSCURRENT to it. If this operation moves the staging label AWSCURRENT from another version to this version, then Secrets Manager also automatically moves the staging label AWSPREVIOUS to the version that AWSCURRENT was removed from.

This operation is idempotent. If you call this operation with a ClientRequestToken that matches an existing version's VersionId, 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 can't modify an existing version; you can only create new ones.

Secrets Manager generates a CloudTrail log entry when you call this action. Do not include sensitive information in request parameters except SecretBinary, SecretString, or RotationToken because it might be logged. For more information, see Logging Secrets Manager events with AWS CloudTrail.

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

Important

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. This is a concern if the command includes the value of a secret. Learn how to Mitigate the risks of using command-line tools to store AWS Secrets Manager secrets.

Request Syntax


{
   "ClientRequestToken": "string",
   "RotationToken": "string",
   "SecretBinary": blob,
   "SecretId": "string",
   "SecretString": "string",
   "VersionStages": [ "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.

ClientRequestToken

A unique identifier for the new version of the secret.

Note

If you use the AWS CLI or one of the AWS SDKs to call this operation, then you can leave this parameter empty. The CLI or SDK generates a random UUID for you and includes it as the value for this parameter in the request.

If you generate a raw HTTP request to the Secrets Manager service endpoint, then you must generate a ClientRequestToken and include it in the request.

This value helps ensure idempotency. Secrets Manager uses this value to prevent the accidental creation of duplicate versions if there are failures and retries during a rotation. We recommend that you generate a UUID-type value to ensure uniqueness of your versions within the specified secret.

If the ClientRequestToken value isn't already associated with a version of the secret then a new version of the secret is created.
If a version with this value already exists and that version's SecretString or SecretBinary values are the same as those in the request then the request is ignored. The operation is idempotent.
If a version with this value already exists and the version of the SecretString and SecretBinary values are different from those in the request, then the request fails because you can't modify a secret version. You can only create new versions to store new secret values.

This value becomes the VersionId of the new version.

Type: String

Length Constraints: Minimum length of 32. Maximum length of 64.

Required: No

RotationToken

A unique identifier that indicates the source of the request. For cross-account rotation (when you rotate a secret in one account by using a Lambda rotation function in another account) and the Lambda rotation function assumes an IAM role to call Secrets Manager, Secrets Manager validates the identity with the rotation token. For more information, see How rotation works.

Sensitive: This field contains sensitive information, so the service does not include it in AWS CloudTrail log entries. If you create your own log entries, you must also avoid logging the information in this field.

Type: String

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

Pattern: ^[a-zA-Z0-9\-]+$

Required: No

SecretBinary

The binary data to encrypt and store in the new version of the secret. To use this parameter in the command-line tools, we recommend that you store your binary data in a file and then pass the contents of the file as a parameter.

You must include SecretBinary or SecretString, but not both.

You can't access this value from the Secrets Manager console.

Type: Base64-encoded binary data object

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

Required: No

SecretId

The ARN or name of the secret to add a new version to.

For an ARN, we recommend that you specify a complete ARN rather than a partial ARN. See Finding a secret from a partial ARN.

If the secret doesn't already exist, use CreateSecret instead.

Type: String

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

Required: Yes

SecretString

The text to encrypt and store in the new version of the secret.

You must include SecretBinary or SecretString, but not both.

We recommend you create the secret string as JSON key/value pairs, as shown in the example.

Type: String

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

Required: No

VersionStages

A list of staging labels to attach to this version of the secret. Secrets Manager uses staging labels to track versions of a secret through the rotation process.

If you specify a staging label that's already associated with a different version of the same secret, then Secrets Manager removes the label from the other version and attaches it to this version. If you specify AWSCURRENT, and it is already attached to another version, then Secrets Manager also moves the staging label AWSPREVIOUS to the version that AWSCURRENT was removed from.

If you don't include VersionStages, then Secrets Manager automatically moves the staging label AWSCURRENT to this version.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 20 items.

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

Required: No

Response Syntax


{
   "ARN": "string",
   "Name": "string",
   "VersionId": "string",
   "VersionStages": [ "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.

Name

The name of the secret.

Type: String

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

VersionId

The unique identifier of the version of the secret.

Type: String

Length Constraints: Minimum length of 32. Maximum length of 64.

VersionStages

The list of staging labels that are currently attached to this version of the secret. Secrets Manager uses staging labels to track a version as it progresses through the secret rotation process.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 20 items.

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.

DecryptionFailure

Secrets Manager can't decrypt the protected secret text using the provided KMS key.

HTTP Status Code: 400

EncryptionFailure

Secrets Manager can't encrypt the protected secret text using the provided KMS key. Check that the KMS key is available, enabled, and not in an invalid state. For more information, see Key state: Effect on your KMS key.

HTTP Status Code: 400

InternalServiceError

An error occurred on the server side.

HTTP Status Code: 500

InvalidParameterException

The parameter name or value is invalid.

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.
The secret is managed by another service, and you must use that service to update it. For more information, see Secrets managed by other AWS services.

HTTP Status Code: 400

LimitExceededException

The request failed because it would exceed one of the Secrets Manager quotas.

HTTP Status Code: 400

ResourceExistsException

A resource with the ID you requested already exists.

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 create a new version of a secret. The ClientRequestToken becomes the VersionId of the new version. 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.PutSecretValue
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",
  "SecretString": "{\"username\":\"david\",\"password\":\"EXAMPLE-PASSWORD\"}",
  "ClientRequestToken": "EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE"
}

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",
  "Name":"MyTestDatabaseSecret",
  "VersionId":"EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE",
  "VersionStages":[
      "AWSCURRENT"
  ]
}