Sign In to the Console
AWS Secrets Manager
API Reference (API Version 2017-10-17)

AWS Documentation » AWS Secrets Manager » API Reference » Actions » GetRandomPassword
The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

GetRandomPassword

Generates a random password of the specified complexity. This operation is intended for use in the Lambda rotation function. Per best practice, we recommend that you specify the maximum length and include every character type that the system you are generating a password for can support.

Minimum permissions

To run this command, you must have the following permissions:

  • secretsmanager:GetRandomPassword

Request Syntax

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

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.

ExcludeCharacters

A string that includes characters that should not be included in the generated password. The default is that all characters from the included sets can be used.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 4096.

Required: No

ExcludeLowercase

Specifies that the generated password should not include lowercase letters. The default if you do not include this switch parameter is that lowercase letters can be included.

Type: Boolean

Required: No

ExcludeNumbers

Specifies that the generated password should not include digits. The default if you do not include this switch parameter is that digits can be included.

Type: Boolean

Required: No

ExcludePunctuation

Specifies that the generated password should not include punctuation characters. The default if you do not include this switch parameter is that punctuation characters can be included.

The following are the punctuation characters that can be included in the generated password if you don't explicitly exclude them with ExcludeCharacters or ExcludePunctuation:

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

Type: Boolean

Required: No

ExcludeUppercase

Specifies that the generated password should not include uppercase letters. The default if you do not include this switch parameter is that uppercase letters can be included.

Type: Boolean

Required: No

IncludeSpace

Specifies that the generated password can include the space character. The default if you do not include this switch parameter is that the space character is not included.

Type: Boolean

Required: No

PasswordLength

The desired length of the generated password. The default value if you do not include this parameter is 32 characters.

Type: Long

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

Required: No

RequireEachIncludedType

A boolean value that specifies whether the generated password must include at least one of every allowed character type. The default value is True and the operation requires at least one of every character type.

Type: Boolean

Required: No

Response Syntax

{
   "RandomPassword": "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.

RandomPassword

A string with the generated password.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 4096.

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

You provided an invalid value for a parameter.

HTTP Status Code: 400

InvalidRequestException

You provided a parameter value that is not valid for the current state of the resource.

Possible causes:

  • You tried to perform the operation on a secret that's currently marked deleted.

  • 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

Example

The following example shows how to request a randomly generated password. This example includes the optional flags to require spaces and at least one character of each included type. It specifies a length of 20 characters.

Sample Request

POST / HTTP/1.1
Host: secretsmanager.region.domain
Accept-Encoding: identity
X-Amz-Target: secretsmanager.GetRandomPassword
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>

{
  "PasswordLength": 20,
  "IncludeSpace": true,
  "RequireEachIncludedType": true
}

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>

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

See Also

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