AWS Secrets Manager 2017-10-17

CancelRotateSecret

$result = $client->cancelRotateSecret([/* ... */]);
$promise = $client->cancelRotateSecretAsync([/* ... */]);

Parameter Syntax

$result = $client->cancelRotateSecret([
    'SecretId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
    'VersionId' => '<string>',
]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InvalidParameterException:

  You provided an invalid value for a parameter.

• InternalServiceError:

  An error occurred on the server side.

• 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.

Examples

Example 1: To cancel scheduled rotation for a secret

The following example shows how to cancel rotation for a secret. The operation sets the RotationEnabled field to false and cancels all scheduled rotations. To resume scheduled rotations, you must re-enable rotation by calling the rotate-secret operation.

$result = $client->cancelRotateSecret([
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'Name',
]

CreateSecret

$result = $client->createSecret([/* ... */]);
$promise = $client->createSecretAsync([/* ... */]);

Parameter Syntax

$result = $client->createSecret([
    'ClientRequestToken' => '<string>',
    'Description' => '<string>',
    'KmsKeyId' => '<string>',
    'Name' => '<string>', // REQUIRED
    'SecretBinary' => <string || resource || Psr\Http\Message\StreamInterface>,
    'SecretString' => '<string>',
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
    'VersionId' => '<string>',
]

Result Details

Errors

• InvalidParameterException:

  You provided an invalid value for a parameter.

• 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.

• LimitExceededException:

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

• EncryptionFailure:

  Secrets Manager can't encrypt the protected secret text using the provided KMS key. Check that the customer master key (CMK) is available, enabled, and not in an invalid state. For more information, see How Key State Affects Use of a Customer Master Key.

• ResourceExistsException:

  A resource with the ID you requested already exists.

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• MalformedPolicyDocumentException:

  The policy document that you provided isn't valid.

• InternalServiceError:

  An error occurred on the server side.

• PreconditionNotMetException:

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

Examples

Example 1: To create a basic secret

The following example shows how to create a secret. The credentials stored in the encrypted secret value are retrieved from a file on disk named mycreds.json.

$result = $client->createSecret([
    'ClientRequestToken' => 'EXAMPLE1-90ab-cdef-fedc-ba987SECRET1',
    'Description' => 'My test database secret created with the CLI',
    'Name' => 'MyTestDatabaseSecret',
    'SecretString' => '{"username":"david","password":"BnQw!XDWgaEeT9XGTT29"}',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
    'VersionId' => 'EXAMPLE1-90ab-cdef-fedc-ba987SECRET1',
]

DeleteResourcePolicy

$result = $client->deleteResourcePolicy([/* ... */]);
$promise = $client->deleteResourcePolicyAsync([/* ... */]);

Parameter Syntax

$result = $client->deleteResourcePolicy([
    'SecretId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InternalServiceError:

  An error occurred on the server side.

• 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.

Examples

Example 1: To delete the resource-based policy attached to a secret

The following example shows how to delete the resource-based policy that is attached to a secret.

$result = $client->deleteResourcePolicy([
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseMasterSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
]

DeleteSecret

$result = $client->deleteSecret([/* ... */]);
$promise = $client->deleteSecretAsync([/* ... */]);

Parameter Syntax

$result = $client->deleteSecret([
    'ForceDeleteWithoutRecovery' => true || false,
    'RecoveryWindowInDays' => <integer>,
    'SecretId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'DeletionDate' => <DateTime>,
    'Name' => '<string>',
]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InvalidParameterException:

  You provided an invalid value for a parameter.

• 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.

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To delete a secret

The following example shows how to delete a secret. The secret stays in your account in a deprecated and inaccessible state until the recovery window ends. After the date and time in the DeletionDate response field has passed, you can no longer recover this secret with restore-secret.

$result = $client->deleteSecret([
    'RecoveryWindowInDays' => 7,
    'SecretId' => 'MyTestDatabaseSecret1',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'DeletionDate' => ,
    'Name' => 'MyTestDatabaseSecret',
]

DescribeSecret

$result = $client->describeSecret([/* ... */]);
$promise = $client->describeSecretAsync([/* ... */]);

Parameter Syntax

$result = $client->describeSecret([
    'SecretId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'DeletedDate' => <DateTime>,
    'Description' => '<string>',
    'KmsKeyId' => '<string>',
    'LastAccessedDate' => <DateTime>,
    'LastChangedDate' => <DateTime>,
    'LastRotatedDate' => <DateTime>,
    'Name' => '<string>',
    'OwningService' => '<string>',
    'RotationEnabled' => true || false,
    'RotationLambdaARN' => '<string>',
    'RotationRules' => [
        'AutomaticallyAfterDays' => <integer>,
    ],
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
    'VersionIdsToStages' => [
        '<SecretVersionIdType>' => ['<string>', ...],
        // ...
    ],
]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To retrieve the details of a secret

The following example shows how to get the details about a secret.

$result = $client->describeSecret([
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Description' => 'My test database secret',
    'KmsKeyId' => 'arn:aws:kms:us-west-2:123456789012:key/EXAMPLE1-90ab-cdef-fedc-ba987KMSKEY1',
    'LastAccessedDate' => ,
    'LastChangedDate' => ,
    'LastRotatedDate' => ,
    'Name' => 'MyTestDatabaseSecret',
    'RotationEnabled' => 1,
    'RotationLambdaARN' => 'arn:aws:lambda:us-west-2:123456789012:function:MyTestRotationLambda',
    'RotationRules' => [
        'AutomaticallyAfterDays' => 30,
    ],
    'Tags' => [
        [
            'Key' => 'SecondTag',
            'Value' => 'AnotherValue',
        ],
        [
            'Key' => 'FirstTag',
            'Value' => 'SomeValue',
        ],
    ],
    'VersionIdsToStages' => [
        'EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE' => [
            'AWSPREVIOUS',
        ],
        'EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE' => [
            'AWSCURRENT',
        ],
    ],
]

GetRandomPassword

$result = $client->getRandomPassword([/* ... */]);
$promise = $client->getRandomPasswordAsync([/* ... */]);

Parameter Syntax

$result = $client->getRandomPassword([
    'ExcludeCharacters' => '<string>',
    'ExcludeLowercase' => true || false,
    'ExcludeNumbers' => true || false,
    'ExcludePunctuation' => true || false,
    'ExcludeUppercase' => true || false,
    'IncludeSpace' => true || false,
    'PasswordLength' => <integer>,
    'RequireEachIncludedType' => true || false,
]);

Parameter Details

Result Syntax

[
    'RandomPassword' => '<string>',
]

Result Details

Errors

• InvalidParameterException:

  You provided an invalid value for a parameter.

• 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.

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To generate a random password

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.

$result = $client->getRandomPassword([
    'IncludeSpace' => 1,
    'PasswordLength' => 20,
    'RequireEachIncludedType' => 1,
]);

Result syntax:

[
    'RandomPassword' => 'N+Z43a,>vx7j O8^*<8i3',
]

GetResourcePolicy

$result = $client->getResourcePolicy([/* ... */]);
$promise = $client->getResourcePolicyAsync([/* ... */]);

Parameter Syntax

$result = $client->getResourcePolicy([
    'SecretId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
    'ResourcePolicy' => '<string>',
]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InternalServiceError:

  An error occurred on the server side.

• 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.

Examples

Example 1: To retrieve the resource-based policy attached to a secret

The following example shows how to retrieve the resource-based policy that is attached to a secret.

$result = $client->getResourcePolicy([
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
    'ResourcePolicy' => '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::123456789012:root"},"Action":"secretsmanager:GetSecretValue","Resource":"*"}]}',
]

GetSecretValue

$result = $client->getSecretValue([/* ... */]);
$promise = $client->getSecretValueAsync([/* ... */]);

Parameter Syntax

$result = $client->getSecretValue([
    'SecretId' => '<string>', // REQUIRED
    'VersionId' => '<string>',
    'VersionStage' => '<string>',
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'CreatedDate' => <DateTime>,
    'Name' => '<string>',
    'SecretBinary' => <string || resource || Psr\Http\Message\StreamInterface>,
    'SecretString' => '<string>',
    'VersionId' => '<string>',
    'VersionStages' => ['<string>', ...],
]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InvalidParameterException:

  You provided an invalid value for a parameter.

• 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.

• DecryptionFailure:

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

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To retrieve the encrypted secret value of a secret

The following example shows how to retrieve the secret string value from the version of the secret that has the AWSPREVIOUS staging label attached. If you want to retrieve the AWSCURRENT version of the secret, then you can omit the VersionStage parameter because it defaults to AWSCURRENT.

$result = $client->getSecretValue([
    'SecretId' => 'MyTestDatabaseSecret',
    'VersionStage' => 'AWSPREVIOUS',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'CreatedDate' => ,
    'Name' => 'MyTestDatabaseSecret',
    'SecretString' => '{ "username":"david", "password":"BnQw&XDWgaEeT9XGTT29"}',
    'VersionId' => 'EXAMPLE1-90ab-cdef-fedc-ba987SECRET1',
    'VersionStages' => [
        'AWSPREVIOUS',
    ],
]

ListSecretVersionIds

$result = $client->listSecretVersionIds([/* ... */]);
$promise = $client->listSecretVersionIdsAsync([/* ... */]);

Parameter Syntax

$result = $client->listSecretVersionIds([
    'IncludeDeprecated' => true || false,
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'SecretId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
    'NextToken' => '<string>',
    'Versions' => [
        [
            'CreatedDate' => <DateTime>,
            'LastAccessedDate' => <DateTime>,
            'VersionId' => '<string>',
            'VersionStages' => ['<string>', ...],
        ],
        // ...
    ],
]

Result Details

Errors

• InvalidNextTokenException:

  You provided an invalid NextToken value.

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To list all of the secret versions associated with a secret

The following example shows how to retrieve a list of all of the versions of a secret, including those without any staging labels.

$result = $client->listSecretVersionIds([
    'IncludeDeprecated' => 1,
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
    'Versions' => [
        [
            'CreatedDate' => ,
            'VersionId' => 'EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE',
            'VersionStages' => [
                'AWSPREVIOUS',
            ],
        ],
        [
            'CreatedDate' => ,
            'VersionId' => 'EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE',
            'VersionStages' => [
                'AWSCURRENT',
            ],
        ],
        [
            'CreatedDate' => ,
            'VersionId' => 'EXAMPLE3-90ab-cdef-fedc-ba987EXAMPLE;',
        ],
    ],
]

ListSecrets

$result = $client->listSecrets([/* ... */]);
$promise = $client->listSecretsAsync([/* ... */]);

Parameter Syntax

$result = $client->listSecrets([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Result Syntax

[
    'NextToken' => '<string>',
    'SecretList' => [
        [
            'ARN' => '<string>',
            'DeletedDate' => <DateTime>,
            'Description' => '<string>',
            'KmsKeyId' => '<string>',
            'LastAccessedDate' => <DateTime>,
            'LastChangedDate' => <DateTime>,
            'LastRotatedDate' => <DateTime>,
            'Name' => '<string>',
            'OwningService' => '<string>',
            'RotationEnabled' => true || false,
            'RotationLambdaARN' => '<string>',
            'RotationRules' => [
                'AutomaticallyAfterDays' => <integer>,
            ],
            'SecretVersionsToStages' => [
                '<SecretVersionIdType>' => ['<string>', ...],
                // ...
            ],
            'Tags' => [
                [
                    'Key' => '<string>',
                    'Value' => '<string>',
                ],
                // ...
            ],
        ],
        // ...
    ],
]

Result Details

Errors

• InvalidParameterException:

  You provided an invalid value for a parameter.

• InvalidNextTokenException:

  You provided an invalid NextToken value.

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To list the secrets in your account

The following example shows how to list all of the secrets in your account.

$result = $client->listSecrets([
]);

Result syntax:

[
    'SecretList' => [
        [
            'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
            'Description' => 'My test database secret',
            'LastChangedDate' => ,
            'Name' => 'MyTestDatabaseSecret',
            'SecretVersionsToStages' => [
                'EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE' => [
                    'AWSCURRENT',
                ],
            ],
        ],
        [
            'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret1-d4e5f6',
            'Description' => 'Another secret created for a different database',
            'LastChangedDate' => ,
            'Name' => 'MyTestDatabaseSecret1',
            'SecretVersionsToStages' => [
                'EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE' => [
                    'AWSCURRENT',
                ],
            ],
        ],
    ],
]

PutResourcePolicy

$result = $client->putResourcePolicy([/* ... */]);
$promise = $client->putResourcePolicyAsync([/* ... */]);

Parameter Syntax

$result = $client->putResourcePolicy([
    'ResourcePolicy' => '<string>', // REQUIRED
    'SecretId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
]

Result Details

Errors

• MalformedPolicyDocumentException:

  The policy document that you provided isn't valid.

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InvalidParameterException:

  You provided an invalid value for a parameter.

• InternalServiceError:

  An error occurred on the server side.

• 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.

Examples

Example 1: To add a resource-based policy to a secret

The following example shows how to add a resource-based policy to a secret.

$result = $client->putResourcePolicy([
    'ResourcePolicy' => '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::123456789012:root"},"Action":"secretsmanager:GetSecretValue","Resource":"*"}]}',
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
]

PutSecretValue

$result = $client->putSecretValue([/* ... */]);
$promise = $client->putSecretValueAsync([/* ... */]);

Parameter Syntax

$result = $client->putSecretValue([
    'ClientRequestToken' => '<string>',
    'SecretBinary' => <string || resource || Psr\Http\Message\StreamInterface>,
    'SecretId' => '<string>', // REQUIRED
    'SecretString' => '<string>',
    'VersionStages' => ['<string>', ...],
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
    'VersionId' => '<string>',
    'VersionStages' => ['<string>', ...],
]

Result Details

Errors

• InvalidParameterException:

  You provided an invalid value for a parameter.

• 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.

• LimitExceededException:

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

• EncryptionFailure:

  Secrets Manager can't encrypt the protected secret text using the provided KMS key. Check that the customer master key (CMK) is available, enabled, and not in an invalid state. For more information, see How Key State Affects Use of a Customer Master Key.

• ResourceExistsException:

  A resource with the ID you requested already exists.

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To store a secret value in a new version of a secret

The following example shows how to create a new version of the secret. Alternatively, you can use the update-secret command.

$result = $client->putSecretValue([
    'ClientRequestToken' => 'EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE',
    'SecretId' => 'MyTestDatabaseSecret',
    'SecretString' => '{"username":"david","password":"BnQw!XDWgaEeT9XGTT29"}',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
    'VersionId' => 'EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE',
    'VersionStages' => [
        'AWSCURRENT',
    ],
]

RestoreSecret

$result = $client->restoreSecret([/* ... */]);
$promise = $client->restoreSecretAsync([/* ... */]);

Parameter Syntax

$result = $client->restoreSecret([
    'SecretId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InvalidParameterException:

  You provided an invalid value for a parameter.

• 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.

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To restore a previously deleted secret

The following example shows how to restore a secret that you previously scheduled for deletion.

$result = $client->restoreSecret([
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
]

RotateSecret

$result = $client->rotateSecret([/* ... */]);
$promise = $client->rotateSecretAsync([/* ... */]);

Parameter Syntax

$result = $client->rotateSecret([
    'ClientRequestToken' => '<string>',
    'RotationLambdaARN' => '<string>',
    'RotationRules' => [
        'AutomaticallyAfterDays' => <integer>,
    ],
    'SecretId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
    'VersionId' => '<string>',
]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InvalidParameterException:

  You provided an invalid value for a parameter.

• InternalServiceError:

  An error occurred on the server side.

• 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.

Examples

Example 1: To configure rotation for a secret

The following example configures rotation for a secret by providing the ARN of a Lambda rotation function (which must already exist) and the number of days between rotation. The first rotation happens immediately upon completion of this command. The rotation function runs asynchronously in the background.

$result = $client->rotateSecret([
    'RotationLambdaARN' => 'arn:aws:lambda:us-west-2:123456789012:function:MyTestDatabaseRotationLambda',
    'RotationRules' => [
        'AutomaticallyAfterDays' => 30,
    ],
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
    'VersionId' => 'EXAMPLE2-90ab-cdef-fedc-ba987SECRET2',
]

Example 2: To request an immediate rotation for a secret

The following example requests an immediate invocation of the secret's Lambda rotation function. It assumes that the specified secret already has rotation configured. The rotation function runs asynchronously in the background.

$result = $client->rotateSecret([
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
]

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Parameter Syntax

$result = $client->tagResource([
    'SecretId' => '<string>', // REQUIRED
    'Tags' => [ // REQUIRED
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• 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.

• InvalidParameterException:

  You provided an invalid value for a parameter.

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To add tags to a secret

The following example shows how to attach two tags each with a Key and Value to a secret. There is no output from this API. To see the result, use the DescribeSecret operation.

$result = $client->tagResource([
    'SecretId' => 'MyExampleSecret',
    'Tags' => [
        [
            'Key' => 'FirstTag',
            'Value' => 'SomeValue',
        ],
        [
            'Key' => 'SecondTag',
            'Value' => 'AnotherValue',
        ],
    ],
]);

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Parameter Syntax

$result = $client->untagResource([
    'SecretId' => '<string>', // REQUIRED
    'TagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• 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.

• InvalidParameterException:

  You provided an invalid value for a parameter.

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To remove tags from a secret

The following example shows how to remove two tags from a secret's metadata. For each, both the tag and the associated value are removed. There is no output from this API. To see the result, use the DescribeSecret operation.

$result = $client->untagResource([
    'SecretId' => 'MyTestDatabaseSecret',
    'TagKeys' => [
        'FirstTag',
        'SecondTag',
    ],
]);

UpdateSecret

$result = $client->updateSecret([/* ... */]);
$promise = $client->updateSecretAsync([/* ... */]);

Parameter Syntax

$result = $client->updateSecret([
    'ClientRequestToken' => '<string>',
    'Description' => '<string>',
    'KmsKeyId' => '<string>',
    'SecretBinary' => <string || resource || Psr\Http\Message\StreamInterface>,
    'SecretId' => '<string>', // REQUIRED
    'SecretString' => '<string>',
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
    'VersionId' => '<string>',
]

Result Details

Errors

• InvalidParameterException:

  You provided an invalid value for a parameter.

• 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.

• LimitExceededException:

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

• EncryptionFailure:

  Secrets Manager can't encrypt the protected secret text using the provided KMS key. Check that the customer master key (CMK) is available, enabled, and not in an invalid state. For more information, see How Key State Affects Use of a Customer Master Key.

• ResourceExistsException:

  A resource with the ID you requested already exists.

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• MalformedPolicyDocumentException:

  The policy document that you provided isn't valid.

• InternalServiceError:

  An error occurred on the server side.

• PreconditionNotMetException:

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

Examples

Example 1: To update the description of a secret

The following example shows how to modify the description of a secret.

$result = $client->updateSecret([
    'ClientRequestToken' => 'EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE',
    'Description' => 'This is a new description for the secret.',
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
]

Example 2: To update the KMS key associated with a secret

This example shows how to update the KMS customer managed key (CMK) used to encrypt the secret value. The KMS CMK must be in the same region as the secret.

$result = $client->updateSecret([
    'KmsKeyId' => 'arn:aws:kms:us-west-2:123456789012:key/EXAMPLE2-90ab-cdef-fedc-ba987EXAMPLE',
    'SecretId' => 'MyTestDatabaseSecret',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
]

Example 3: To create a new version of the encrypted secret value

The following example shows how to create a new version of the secret by updating the SecretString field. Alternatively, you can use the put-secret-value operation.

$result = $client->updateSecret([
    'SecretId' => 'MyTestDatabaseSecret',
    'SecretString' => '{JSON STRING WITH CREDENTIALS}',
]);

Result syntax:

[
    'ARN' => 'aws:arn:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
    'VersionId' => 'EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE',
]

UpdateSecretVersionStage

$result = $client->updateSecretVersionStage([/* ... */]);
$promise = $client->updateSecretVersionStageAsync([/* ... */]);

Parameter Syntax

$result = $client->updateSecretVersionStage([
    'MoveToVersionId' => '<string>',
    'RemoveFromVersionId' => '<string>',
    'SecretId' => '<string>', // REQUIRED
    'VersionStage' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'ARN' => '<string>',
    'Name' => '<string>',
]

Result Details

Errors

• ResourceNotFoundException:

  We can't find the resource that you asked for.

• InvalidParameterException:

  You provided an invalid value for a parameter.

• 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.

• LimitExceededException:

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

• InternalServiceError:

  An error occurred on the server side.

Examples

Example 1: To add a staging label attached to a version of a secret

The following example shows you how to add a staging label to a version of a secret. You can review the results by running the operation ListSecretVersionIds and viewing the VersionStages response field for the affected version.

$result = $client->updateSecretVersionStage([
    'MoveToVersionId' => 'EXAMPLE1-90ab-cdef-fedc-ba987SECRET1',
    'SecretId' => 'MyTestDatabaseSecret',
    'VersionStage' => 'STAGINGLABEL1',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
]

Example 2: To delete a staging label attached to a version of a secret

The following example shows you how to delete a staging label that is attached to a version of a secret. You can review the results by running the operation ListSecretVersionIds and viewing the VersionStages response field for the affected version.

$result = $client->updateSecretVersionStage([
    'RemoveFromVersionId' => 'EXAMPLE1-90ab-cdef-fedc-ba987SECRET1',
    'SecretId' => 'MyTestDatabaseSecret',
    'VersionStage' => 'STAGINGLABEL1',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
]

Example 3: To move a staging label from one version of a secret to another

The following example shows you how to move a staging label that is attached to one version of a secret to a different version. You can review the results by running the operation ListSecretVersionIds and viewing the VersionStages response field for the affected version.

$result = $client->updateSecretVersionStage([
    'MoveToVersionId' => 'EXAMPLE2-90ab-cdef-fedc-ba987SECRET2',
    'RemoveFromVersionId' => 'EXAMPLE1-90ab-cdef-fedc-ba987SECRET1',
    'SecretId' => 'MyTestDatabaseSecret',
    'VersionStage' => 'AWSCURRENT',
]);

Result syntax:

[
    'ARN' => 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestDatabaseSecret-a1b2c3',
    'Name' => 'MyTestDatabaseSecret',
]