AWS Secrets Manager

(1)

AWS Secrets Manager

API Reference

API Version 2017-10-17

(2)

AWS Secrets Manager: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

AWS Secrets Manager provides a service to enable you to store, manage, and retrieve, secrets.

This guide provides descriptions of the Secrets Manager API. For more information about using this service, see the AWS Secrets Manager User Guide.

API Version

This version of the Secrets Manager API Reference documents the Secrets Manager API version 2017-10-17.

Although you can make direct calls to the Secrets Manager HTTPS Query API, we recommend that you use one of the SDKs instead. The SDK performs many useful tasks you otherwise must perform manually. For example, the SDKs automatically sign your requests and convert responses into a structure syntactically appropriate to your language.

For SDKs, see:

• C++

• Java

• PHP

• Python

• Ruby

• Node.js

Making HTTPS query requests

The Query API for AWS Secrets Manager lets you call service operations. Query API requests are HTTPS requests that must contain an Action parameter to indicate the operation to be performed. AWS Secrets Manager supports GET and POST requests for all operations. The API doesn't require you to use GET for some operations and POST for others. However, GET requests are subject to the limitation size of a URL. Although this limit depends on the browser , a typical limit is 2048 bytes. Therefore, for Query API requests that require larger sizes, you must use a POST request.

The API returns the response in an XML document. For details about the response, see the individual API description pages in the AWS Organizations API reference.

Because the Query API returns sensitive information such as security credentials, you must use HTTPS to encrypt all API requests.

When you send HTTP requests to AWS, you must sign the requests so AWS can identify the sender. You must use Signature Version 4. If you have an existing application that uses Signature Version 2, you must update it to use Signature Version 4.

You sign requests with your AWS access key, which consists of an access key ID and a secret access key.

We strongly recommend you don't create an access key for your root account. Anyone who has the access key for your root account has unrestricted access to all the resources in your account. Instead, create an access key for an IAM user account with permissions required for the task at hand. As another option, use AWS Security Token Service to generate temporary security credentials, and use those credentials to sign requests.

For more information, see the following:

(8)

• AWS Security Credentials. Provides general information about the types of credentials you can use to access AWS.

• IAM Best Practices. Oﬀers suggestions for using the IAM service to help secure your AWS resources, including those in Secrets Manager.

• Temporary Credentials. Describes how to create and use temporary security credentials.

When you use the AWS Command Line Interface (AWS CLI) or one of the AWS SDKs to make requests to AWS, these tools automatically sign the requests for you with the access key that you specify when you conﬁgure the tools.

The JSON that AWS Secrets Manager expects as your request parameters and the service returns as a response to HTTP query requests contain single, long strings without line breaks or white space formatting. The JSON shown in the examples in this guide displays the code formatted with both line breaks and white space to improve readability. When example input parameters can also cause long strings extending beyond the screen, you can insert line breaks to enhance readability. You should always submit the input as a single JSON text string.

Support and Feedback for AWS Secrets Manager

We welcome your feedback. Send your comments to [email protected], or post your feedback and questions in the AWS Secrets Manager Discussion Forum. For more information about the AWS Discussion Forums, see Forums Help.

Logging API Requests

AWS Secrets Manager supports AWS CloudTrail, a service that records AWS API calls for your AWS account and delivers log files to an Amazon S3 bucket. By using information that's collected by AWS CloudTrail, you can determine the requests successfully made to Secrets Manager, who made the request, when it was made, and so on. For more about AWS Secrets Manager and support for AWS CloudTrail, see Logging AWS Secrets Manager Events with AWS CloudTrail in the AWS Secrets Manager User Guide. To learn more about CloudTrail, including enabling it and find your log files, see the AWS CloudTrail User Guide.

This document was last published on March 6, 2022.

(9)

Actions

The following actions are supported:

• CancelRotateSecret (p. 4)

• CreateSecret (p. 7)

• DeleteResourcePolicy (p. 14)

• DeleteSecret (p. 17)

• DescribeSecret (p. 21)

• GetRandomPassword (p. 27)

• GetResourcePolicy (p. 31)

• GetSecretValue (p. 34)

• ListSecrets (p. 39)

• ListSecretVersionIds (p. 44)

• PutResourcePolicy (p. 48)

• PutSecretValue (p. 52)

• RemoveRegionsFromReplication (p. 58)

• ReplicateSecretToRegions (p. 62)

• RestoreSecret (p. 65)

• RotateSecret (p. 68)

• StopReplicationToReplica (p. 74)

• TagResource (p. 77)

• UntagResource (p. 80)

• UpdateSecret (p. 83)

• UpdateSecretVersionStage (p. 90)

• ValidateResourcePolicy (p. 96)

(10)

CancelRotateSecret

Turns oﬀ automatic rotation, and if a rotation is currently in progress, cancels the rotation.

To turn on automatic rotation again, call RotateSecret (p. 68).

NoteIf you cancel a rotation in progress, it can leave the VersionStage labels in an unexpected state. Depending on the step of the rotation in progress, you might need to remove the staging label AWSPENDING from the partially created version, speciﬁed by the VersionId response value. We recommend you also evaluate the partially rotated new version to see if it should be deleted. You can delete a version by removing all staging labels from it.

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

Request Syntax

{ "SecretId": "string"

}

Request Parameters

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

The request accepts the following data in JSON format.

SecretId (p. 4)

The ARN or name of the secret.

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", "Name": "string", "VersionId": "string"

}

Response Elements

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

(11)

Errors

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

ARN (p. 4)

The ARN of the secret.

Type: String

Name (p. 4)

The name of the secret.

Type: String

VersionId (p. 4)

The unique identiﬁer of the version of the secret created during the rotation. This version might not be complete, and should be evaluated for possible deletion. We recommend that you remove the VersionStage value AWSPENDING from this version so that Secrets Manager can delete it. Failing to clean up a cancelled rotation can block you from starting future rotations.

Type: String

Errors

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

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 conﬁgured and you didn't include such an ARN as a parameter in this call.

HTTP Status Code: 400 ResourceNotFoundException

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

HTTP Status Code: 400

(12)

Examples

Example

The following example shows how to cancel rotation for a secret.

Sample Request

POST / HTTP/1.1

Host: secretsmanager.region.domain Accept-Encoding: identity

X-Amz-Target: secretsmanager.CancelRotateSecret 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"

}

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"

}

CreateSecret

Creates a new secret. A secret is a set of credentials, such as a user name and password, that you store in an encrypted form in Secrets Manager. The secret also includes the connection information to access a database or other service, which Secrets Manager doesn't encrypt. A secret in Secrets Manager consists of both the protected secret data and the important information needed to manage the secret.

For information about creating a secret in the console, see Create a secret.

To create a secret, you can provide the secret value to be encrypted in either the SecretString parameter or the SecretBinary parameter, but not both. If you include SecretString or

SecretBinary then Secrets Manager creates an initial secret version and automatically attaches the staging label AWSCURRENT to it.

If you don't specify an AWS KMS encryption key, Secrets Manager uses the AWS managed key aws/

secretsmanager. If this key doesn't already exist in your account, then Secrets Manager creates it for you automatically. All users and roles in the AWS account automatically have access to use aws/

secretsmanager. Creating aws/secretsmanager can result in a one-time signiﬁcant delay in returning the result.

If the secret is in a diﬀerent AWS account from the credentials calling the API, then you can't use aws/

secretsmanager to encrypt the secret, and you must create and use a customer managed AWS KMS key.

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

Request Syntax

{ "AddReplicaRegions": [ {

"KmsKeyId": "string", "Region": "string"

} ],

"ClientRequestToken": "string", "Description": "string",

"ForceOverwriteReplicaSecret": boolean, "KmsKeyId": "string",

"Name": "string", "SecretBinary": blob, "SecretString": "string", "Tags": [

{

"Key": "string", "Value": "string"

} ] }

Request Parameters

(14)

Request Parameters

AddReplicaRegions (p. 7)

A list of Regions and AWS KMS keys to replicate secrets.

Type: Array of ReplicaRegionType (p. 101) objects Array Members: Minimum number of 1 item.

Required: No

ClientRequestToken (p. 7)

If you include SecretString or SecretBinary, then Secrets Manager creates an initial version for the secret, and this parameter speciﬁes the unique identiﬁer for the new version.

NoteIf 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 don't use the SDK and instead generate a raw HTTP request to the Secrets Manager service endpoint, then you must generate a ClientRequestToken yourself for the new version and include the value 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 speciﬁed 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 the version SecretString and SecretBinary values are the same as those in the request, then the request is ignored.

• If a version with this value already exists and that version's SecretString and SecretBinary values are diﬀerent from those in the request, then the request fails because you cannot modify an existing version. Instead, use PutSecretValue (p. 52) to create a new version.

This value becomes the VersionId of the new version.

Type: String

Required: No Description (p. 7)

The description of the secret.

Type: String

Length Constraints: Maximum length of 2048.

Required: No

ForceOverwriteReplicaSecret (p. 7)

Speciﬁes whether to overwrite a secret with the same name in the destination Region.

Type: Boolean Required: No KmsKeyId (p. 7)

The ARN, key ID, or alias of the AWS KMS key that Secrets Manager uses to encrypt the secret value in the secret.

To use a AWS KMS key in a diﬀerent account, use the key ARN or the alias ARN.

(15)

Request Parameters

If you don't specify this value, then Secrets Manager uses the key aws/secretsmanager. If that key doesn't yet exist, then Secrets Manager creates it for you automatically the ﬁrst time it encrypts the secret value.

If the secret is in a diﬀerent AWS account from the credentials calling the API, then you can't use aws/secretsmanager to encrypt the secret, and you must create and use a customer managed AWS KMS key.

Type: String

Required: No Name (p. 7)

The name of the new secret.

The secret name can contain ASCII letters, numbers, and the following characters: /_+=.@- Do not end your secret name with a hyphen followed by six characters. If you do so, you risk confusion and unexpected results when searching for a secret by partial ARN. Secrets Manager automatically adds a hyphen and six random characters after the secret name at the end of the ARN.

Type: String

Required: Yes SecretBinary (p. 7)

The binary data to encrypt and store in the new version of the secret. We recommend that you store your binary data in a ﬁle and then pass the contents of the ﬁle as a parameter.

Either SecretString or SecretBinary must have a value, but not both.

This parameter is not available in the Secrets Manager console.

Type: Base64-encoded binary data object

Required: No SecretString (p. 7)

The text data to encrypt and store in this new version of the secret. We recommend you use a JSON structure of key/value pairs for your secret value.

Either SecretString or SecretBinary must have a value, but not both.

If you create a secret by using the Secrets Manager console then Secrets Manager puts the

protected secret text in only the SecretString parameter. The Secrets Manager console stores the information as a JSON structure of key/value pairs that a Lambda rotation function can parse.

Type: String

Required: No Tags (p. 7)

A list of tags to attach to the secret. Each tag is a key and value pair of strings in a JSON text string, for example:

(16)

Response Syntax

[{"Key":"CostCenter","Value":"12345"}, {"Key":"environment","Value":"production"}]

Secrets Manager tag key names are case sensitive. A tag with the key "ABC" is a diﬀerent tag from one with key "abc".

If you check tags in permissions policies as part of your security strategy, then adding or removing a tag can change permissions. If the completion of this operation would result in you losing your permissions for this secret, then Secrets Manager blocks the operation and returns an Access Denied error. For more information, see Control access to secrets using tags and Limit access to identities with tags that match secrets' tags.

For information about how to format a JSON parameter for the various command line tool

environments, see Using JSON for Parameters. If your command-line tool or SDK requires quotation marks around the parameter, you should use single quotes to avoid confusion with the double quotes required in the JSON text.

The following restrictions apply to tags:

• Maximum number of tags per secret: 50

• Maximum key length: 127 Unicode characters in UTF-8

• Maximum value length: 255 Unicode characters in UTF-8

• Tag keys and values are case sensitive.

• Do not use the aws: prefix in your tag names or values because AWS reserves it for AWS use. You can't edit or delete tag names or values with this prefix. Tags with this prefix do not count against your tags per secret limit.

• If you use your tagging schema across multiple services and resources, other services might have restrictions on allowed characters. Generally allowed characters: letters, spaces, and numbers representable in UTF-8, plus the following special characters: + - = . _ : / @.

Type: Array of Tag (p. 111) objects Required: No

Response Syntax

{ "ARN": "string", "Name": "string", "ReplicationStatus": [ {

"KmsKeyId": "string", "LastAccessedDate": number, "Region": "string",

"Status": "string", "StatusMessage": "string"

} ],

"VersionId": "string"

}

Response Elements

(17)

Errors

ARN (p. 10)

The ARN of the new secret. The ARN includes the name of the secret followed by six random characters. This ensures that if you create a new secret with the same name as a deleted secret, then users with access to the old secret don't get access to the new secret because the ARNs are diﬀerent.

Type: String

Name (p. 10)

The name of the new secret.

Type: String

ReplicationStatus (p. 10)

A list of the replicas of this secret and their status:

• Failed, which indicates that the replica was not created.

• InProgress, which indicates that Secrets Manager is in the process of creating the replica.

• InSync, which indicates that the replica was created.

Type: Array of ReplicationStatusType (p. 102) objects VersionId (p. 10)

The unique identiﬁer associated with the version of the new secret.

Type: String

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: Eﬀect on your KMS key.

HTTP Status Code: 400 InternalServiceError

(18)

Examples

Possible causes:

HTTP Status Code: 400 LimitExceededException

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

MalformedPolicyDocumentException The resource policy has syntax errors.

HTTP Status Code: 400 PreconditionNotMetException

The request failed because you did not complete all the prerequisite steps.

HTTP Status Code: 400 ResourceExistsException

A resource with the ID you requested already exists.

Examples

Example

The following example shows how to create a secret. Secrets Manager retrieves the credentials stored in the encrypted secret value from a ﬁle on disk named mycreds.json. For an example of mycreds.json, see Creating a secret. 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

X-Amz-Target: secretsmanager.CreateSecret Content-Type: application/x-amz-json-1.1 User-Agent: <user-agent-string>

X-Amz-Date: <date>

(19)

See Also

{ "Name": "MyTestDatabaseSecret",

"Description": "My test database secret created with the CLI",

"SecretString": "{\"username\":\"david\",\"password\":\"EXAMPLE-PASSWORD\"}", "ClientRequestToken": "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1"

}

Sample Response

{ "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret- a1b2c3",

"Name":"MyTestDatabaseSecret",

"VersionId": "EXAMPLE1-90ab-cdef-fedc-ba987SECRET1"

}

DeleteResourcePolicy

Deletes the resource-based permission policy attached to the secret. To attach a policy to a secret, use PutResourcePolicy (p. 48).

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

Request Syntax

}

Request Parameters

SecretId (p. 14)

The ARN or name of the secret to delete the attached resource-based policy for.

Type: String

Required: Yes

Response Syntax

{

"ARN": "string", "Name": "string"

}

Response Elements

ARN (p. 14)

The ARN of the secret that the resource-based policy was deleted for.

Type: String

(21)

Errors

Name (p. 14)

The name of the secret that the resource-based policy was deleted for.

Type: String

Errors

Possible causes:

Examples

Example

The following example shows how to delete the resource-based policy that's attached to a secret.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

X-Amz-Target: secretsmanager.DeleteResourcePolicy Content-Type: application/x-amz-json-1.1

User-Agent: <user-agent-string>

X-Amz-Date: <date>

(22)

See Also

{ "SecretId": "MyTestDatabaseSecret"

}

Sample Response

"Name": "MyTestDatabaseSecret"

}

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 speciﬁes 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 speciﬁc time after the recovery window for the permanent delete to occur.

At any time before recovery window ends, you can use RestoreSecret (p. 65) 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, ﬁrst cancel the deletion with RestoreSecret (p. 65) 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

ForceDeleteWithoutRecovery (p. 17)

Speciﬁes 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 oﬀ 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

(24)

Response Syntax

Required: No

RecoveryWindowInDays (p. 17)

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 (p. 17)

The ARN or name of the secret to delete.

Type: String

Required: Yes

Response Syntax

{

"ARN": "string",

"DeletionDate": number, "Name": "string"

}

Response Elements

ARN (p. 18)

Type: String

DeletionDate (p. 18)

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 (p. 18)

Type: String

(25)

Errors

Possible causes:

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

X-Amz-Target: secretsmanager.DeleteSecret Content-Type: application/x-amz-json-1.1 User-Agent: <user-agent-string>

X-Amz-Date: <date>

{

"SecretId": "MyTestDatabaseSecret", "RecoveryWindowInDays": 7

}

(26)

See Also

Sample Response

{

"ARN":"arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", "DeletionDate":1.524085349095E9,

"Name":"MyTestDatabaseSecret"

}

DescribeSecret

Retrieves the details of a secret. It does not include the encrypted secret value. Secrets Manager only returns ﬁelds that have a value in the response.

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

Request Syntax

}

Request Parameters

The ARN or name of the secret.

Type: String

Required: Yes

Response Syntax

{ "ARN": "string", "CreatedDate": number, "DeletedDate": number, "Description": "string", "KmsKeyId": "string", "LastAccessedDate": number, "LastChangedDate": number, "LastRotatedDate": number, "Name": "string",

"OwningService": "string", "PrimaryRegion": "string", "ReplicationStatus": [ {

"KmsKeyId": "string", "LastAccessedDate": number, "Region": "string",

"Status": "string", "StatusMessage": "string"

} ],

"RotationEnabled": boolean,

(28)

Response Elements

"RotationLambdaARN": "string", "RotationRules": {

"AutomaticallyAfterDays": number, "Duration": "string",

"ScheduleExpression": "string"

},

"Tags": [ {

"Key": "string", "Value": "string"

} ],

"VersionIdsToStages": { "string" : [ "string" ] }}

Response Elements

ARN (p. 21)

Type: String

CreatedDate (p. 21)

The date the secret was created.

Type: Timestamp DeletedDate (p. 21)

The date the secret is scheduled for deletion. If it is not scheduled for deletion, this ﬁeld is omitted.

When you delete a secret, Secrets Manager requires a recovery window of at least 7 days before deleting the secret. Some time after the deleted date, Secrets Manager deletes the secret, including all of its versions.

If a secret is scheduled for deletion, then its details, including the encrypted secret value, is not accessible. To cancel a scheduled deletion and restore access to the secret, use RestoreSecret (p. 65).

Type: Timestamp Description (p. 21)

The description of the secret.

Type: String

Length Constraints: Maximum length of 2048.

KmsKeyId (p. 21)

The ARN of the AWS KMS key that Secrets Manager uses to encrypt the secret value. If the secret is encrypted with the AWS managed key aws/secretsmanager, this ﬁeld is omitted.

Type: String

(29)

Response Elements

LastAccessedDate (p. 21)

The last date that the secret value was retrieved. This value does not include the time. This ﬁeld is omitted if the secret has never been retrieved.

Type: Timestamp LastChangedDate (p. 21)

The last date and time that this secret was modiﬁed in any way.

Type: Timestamp LastRotatedDate (p. 21)

The last date and time that Secrets Manager rotated the secret. If the secret isn't conﬁgured for rotation, Secrets Manager returns null.

Type: String

OwningService (p. 21)

The name of the service that created this secret.

Type: String

PrimaryRegion (p. 21)

The Region the secret is in. If a secret is replicated to other Regions, the replicas are listed in ReplicationStatus.

Type: String

Pattern: ^([a-z]+-)+\d+$

ReplicationStatus (p. 21)

A list of the replicas of this secret and their status:

• Failed, which indicates that the replica was not created.

• InProgress, which indicates that Secrets Manager is in the process of creating the replica.

• InSync, which indicates that the replica was created.

Type: Array of ReplicationStatusType (p. 102) objects RotationEnabled (p. 21)

Speciﬁes whether automatic rotation is turned on for this secret.

To turn on rotation, use RotateSecret (p. 68). To turn oﬀ rotation, use CancelRotateSecret (p. 4).

Type: Boolean

(30)

Errors

RotationLambdaARN (p. 21)

The ARN of the Lambda function that Secrets Manager invokes to rotate the secret.

Type: String

RotationRules (p. 21)

The rotation schedule and Lambda function for this secret. If the secret previously had rotation turned on, but it is now turned off, this field shows the previous rotation schedule and rotation function. If the secret never had rotation turned on, this field is omitted.

Type: RotationRulesType (p. 104) object Tags (p. 21)

The list of tags attached to the secret. To add tags to a secret, use TagResource (p. 77). To remove tags, use UntagResource (p. 80).

Type: Array of Tag (p. 111) objects VersionIdsToStages (p. 21)

A list of the versions of the secret that have staging labels attached. Versions that don't have staging labels are considered deprecated and Secrets Manager can delete them.

Secrets Manager uses staging labels to indicate the status of a secret version during rotation. The three staging labels for rotation are:

• AWSCURRENT, which indicates the current version of the secret.

• AWSPENDING, which indicates the version of the secret that contains new secret information that will become the next current version when rotation ﬁnishes.

During rotation, Secrets Manager creates an AWSPENDING version ID before creating the new secret version. To check if a secret version exists, call GetSecretValue (p. 34).

• AWSPREVIOUS, which indicates the previous current version of the secret. You can use this as the last known good version.

For more information about rotation and staging labels, see How rotation works.

Type: String to array of strings map

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

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

Errors

(31)

Examples

Example

The following example shows how to get the details about a secret. 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

X-Amz-Target: secretsmanager.DescribeSecret Content-Type: application/x-amz-json-1.1 User-Agent: <user-agent-string>

X-Amz-Date: <date>

}

Sample Response

{

"ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret- a1b2c3",

"Name": "MyTestDatabaseSecret",

"Description": "My test database secret created with the CLI", "LastChangedDate": 1523477145.729,

"LastAccessedDate": 1606269226, "RotationEnabled": true,

"RotationLambdaARN": "arn:aws:lambda:us-

west-2:123456789012:function:MyTestRotationLambda", "RotationRules": {

"AutomaticallyAfterDays": 14,

"ScheduleExpression": "cron(0 16 1,15 * ? *)", "Duration": "2h"

}, "LastRotatedDate": 1525747253.72 "Tags": [

{

(32)

See Also

"Key": "SecondTag", "Value": "AnotherValue"

}, {

"Key": "FirstTag", "Value": "SomeValue"

}

], "VersionIdsToStages": {

"EXAMPLE1-90ab-cdef-fedc-ba987SECRET1": [ "AWSPREVIOUS"

],

"EXAMPLE2-90ab-cdef-fedc-ba987SECRET2": [ "AWSCURRENT"

] } }

GetRandomPassword

Generates a random password. We recommend that you specify the maximum length and include every character type that the system you are generating a password for can support.

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

Request Syntax

{ "ExcludeCharacters": "string", "ExcludeLowercase": boolean, "ExcludeNumbers": boolean, "ExcludePunctuation": boolean, "ExcludeUppercase": boolean, "IncludeSpace": boolean, "PasswordLength": number,

"RequireEachIncludedType": boolean }

Request Parameters

ExcludeCharacters (p. 27)

A string of the characters that you don't want in the password.

Type: String

Required: No

ExcludeLowercase (p. 27)

Speciﬁes whether to exclude lowercase letters from the password. If you don't include this switch, the password can contain lowercase letters.

Type: Boolean Required: No ExcludeNumbers (p. 27)

Speciﬁes whether to exclude numbers from the password. If you don't include this switch, the password can contain numbers.

Type: Boolean Required: No

ExcludePunctuation (p. 27)

Speciﬁes whether to exclude the following punctuation characters from the password: ! " # $

% & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~. If you don't include this switch, the password can contain punctuation.

(34)

Response Syntax

ExcludeUppercase (p. 27)

Speciﬁes whether to exclude uppercase letters from the password. If you don't include this switch, the password can contain uppercase letters.

Type: Boolean Required: No IncludeSpace (p. 27)

Speciﬁes whether to include the space character. If you include this switch, the password can contain space characters.

Type: Boolean Required: No PasswordLength (p. 27)

The length of the password. If you don't include this parameter, the default length is 32 characters.

Type: Long

Valid Range: Minimum value of 1. Maximum value of 4096.

Required: No

RequireEachIncludedType (p. 27)

Speciﬁes whether to include at least one upper and lowercase letter, one number, and one punctuation. If you don't include this switch, the password contains at least one of every character type.

Response Syntax

{

"RandomPassword": "string"

}

Response Elements

RandomPassword (p. 28) A string with the password.

Type: String

(35)

Errors

Possible causes:

Examples

Example

The following example shows how to request a randomly generated password of 20 characters.

Sample Request

POST / HTTP/1.1

X-Amz-Target: secretsmanager.GetRandomPassword Content-Type: application/x-amz-json-1.1 User-Agent: <user-agent-string>

X-Amz-Date: <date>

{ "PasswordLength": 20 }

Sample Response

(36)

See Also

{ "RandomPassword":"N+Z43a,>vx7j O8^*<8i3"

}

GetResourcePolicy

Retrieves the JSON text of the resource-based policy document attached to the secret. For more

information about permissions policies attached to a secret, see Permissions policies attached to a secret.

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

Request Syntax

}

Request Parameters

The ARN or name of the secret to retrieve the attached resource-based policy for.

Type: String

Required: Yes

Response Syntax

{

"ARN": "string", "Name": "string",

"ResourcePolicy": "string"

}

Response Elements

ARN (p. 31)

The ARN of the secret that the resource-based policy was retrieved for.

Type: String

(38)

Errors

Name (p. 31)

The name of the secret that the resource-based policy was retrieved for.

Type: String

ResourcePolicy (p. 31)

A JSON-formatted string that contains the permissions policy attached to the secret. For more information about permissions policies, see Authentication and access control for Secrets Manager.

Type: String

Errors

Possible causes:

Examples

Example

The following example shows how to retrieve the resource-based policy attached to a secret. 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.

(39)

See Also

Sample Request

POST / HTTP/1.1

X-Amz-Target: secretsmanager.GetResourcePolicy Content-Type: application/x-amz-json-1.1 User-Agent: <user-agent-string>

X-Amz-Date: <date>

}

Sample Response

"Name": "MyTestDatabaseSecret",

"ResourcePolicy": "{\"Version\":\"2012-10-17\",\"Statement\":{\"Effect\":\"Allow\",

\"Principal\":{\"AWS\":[\"arn:aws:iam::111122223333:root\",\"arn:aws:iam::444455556666:root

\"]},\"Action\":[\"secretsmanager:GetSecretValue\"],\"Resource\":\"*\"}}"

}

GetSecretValue

Retrieves the contents of the encrypted ﬁelds SecretString or SecretBinary from the speciﬁed version of a secret, whichever contains content.

We recommend that you cache your secret values by using client-side caching. Caching secrets improves speed and reduces your costs. For more information, see Cache secrets for your applications.

Required permissions: secretsmanager:GetSecretValue. If the secret is encrypted using a customer-managed key instead of the AWS managed key aws/secretsmanager, then you also need kms:Decrypt permissions for that key. For more information, see IAM policy actions for Secrets Manager and Authentication and access control in Secrets Manager.

Request Syntax

{ "SecretId": "string", "VersionId": "string", "VersionStage": "string"

}

Request Parameters

The ARN or name of the secret to retrieve.

Type: String

Required: Yes VersionId (p. 34)

The unique identiﬁer of the version of the secret to retrieve. If you include both this parameter and VersionStage, the two parameters must refer to the same secret version. If you don't specify either a VersionStage or VersionId, then Secrets Manager returns the AWSCURRENT version.

This value is typically a UUID-type value with 32 hexadecimal digits.

Type: String

Required: No VersionStage (p. 34)

The staging label of the version of the secret to retrieve.

Secrets Manager uses staging labels to keep track of diﬀerent versions during the rotation process. If you include both this parameter and VersionId, the two parameters must refer to the same secret

(41)

Response Syntax

version. If you don't specify either a VersionStage or VersionId, Secrets Manager returns the AWSCURRENT version.

Type: String

Required: No

Response Syntax

{

"ARN": "string", "CreatedDate": number, "Name": "string", "SecretBinary": blob, "SecretString": "string", "VersionId": "string",

"VersionStages": [ "string" ] }

Response Elements

ARN (p. 35)

Type: String

CreatedDate (p. 35)

The date and time that this version of the secret was created. If you don't specify which version in VersionId or VersionStage, then Secrets Manager uses the AWSCURRENT version.

The friendly name of the secret.

Type: String

SecretBinary (p. 35)

The decrypted secret value, if the secret value was originally provided as binary data in the form of a byte array. The response parameter represents the binary data as a base64-encoded string.

If the secret was created by using the Secrets Manager console, or if the secret value was originally provided as a string, then this ﬁeld is omitted. The secret value appears in SecretString instead.

Type: Base64-encoded binary data object

(42)

Errors

SecretString (p. 35)

The decrypted secret value, if the secret value was originally provided as a string or through the Secrets Manager console.

If this secret was created by using the console, then Secrets Manager stores the information as a JSON structure of key/value pairs.

Type: String

VersionId (p. 35)

The unique identiﬁer of this version of the secret.

Type: String

VersionStages (p. 35)

A list of all of the staging labels currently attached to this version of the secret.

Type: Array of strings

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

Errors

DecryptionFailure

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

HTTP Status Code: 400 InternalServiceError

Possible causes:

(43)

Examples

ResourceNotFoundException

Examples

Example

The following example shows how to retrieve the secret value from a secret. 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

X-Amz-Target: secretsmanager.GetSecretValue Content-Type: application/x-amz-json-1.1 User-Agent: <user-agent-string>

X-Amz-Date: <date>

{ "SecretId": "MyTestDatabaseSecret", }

Sample Response

{ "ARN":"arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3", "CreatedDate":1.523477145713E9,

"Name":"MyTestDatabaseSecret",

"SecretString":"{\n \"username\":\"david\",\n \"password\":\"EXAMPLE-PASSWORD\"\n}\n", "VersionId":"EXAMPLE1-90ab-cdef-fedc-ba987SECRET1"

}

AWS Secrets Manager

AWS Secrets Manager

API Reference

API Version 2017-10-17

AWS Secrets Manager: API Reference

Table of Contents

Welcome

Actions

CancelRotateSecret

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

CreateSecret

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

DeleteResourcePolicy

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

DeleteSecret

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

DescribeSecret

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

GetRandomPassword

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

GetResourcePolicy

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors