Update an Existing Password

PUT /winapi/passwords

An existing Password object can be updated by making a PUT request on the URL, with appropriate fields forming the HTTP message body. Only the fields provided in the data block will be updated; any unspecified fields will remain unchanged. When using this method, it is best to specify only those fields you wish to change.

Note 1: If this password has any associated Password Reset Tasks, they will be queued an executed by the Passwordstate Windows Service - please see output details below for Queued Password Reset Tasks.

Note 2: If you need to specify the AccountTypeID values, you can go to the screen Administration -> Passwordstate Administration -> Images and Account Types, and click on the 'Toggle ID Column Visibility' button to determine the appropriate value.

This method returns the complete updated Password object, as described above.

# PowerShell Request
#JSON data for the object
$Body = @{
PasswordID  = $PasswordListID
Password        = "JENN-ZHn#3+A^yc"
}

$jsonData = $Body | ConvertTo-Json

$PasswordstateUrl = 'https://passwordstate/winapi/passwords'
$result = Invoke-Restmethod -Method Put -Uri $PasswordstateUrl -ContentType "application/json" -Body $jsonData -UseDefaultCredentials

# Response
HTTP/1.1 200          
[
{
    "PasswordID": 46411,
    "Title": "forum4",
    "UserName": "login2",
    "Description": "My login to forum4",
    "GenericField1": "loginasa",
    "GenericField2": "",
    "GenericField3": "",
    "GenericField4": "",
    "GenericField5": "",
    "GenericField6": "",
    "GenericField7": "",
    "GenericField8": "",
    "GenericField9": "",
    "GenericField10": "",
    "GenericFieldInfo": [
        {
            "GenericFieldID": "GenericField1",
            "DisplayName": "Pin Number",
            "Value": "0000"
        },
        {
            "GenericFieldID": "GenericField2",
            "DisplayName": "Surname",
            "Value": "Reznor"
        }
    ],
    "AccountTypeID": 0,
    "Notes": "",
    "URL": "http://www.microsoft.com",
    "Password": "JENN-ZHn#3+A^yc",
    "ExpiryDate": "23/08/2012",
    "AllowExport": true,
    "AccountType": "",
    "OTP": "",
    "WebUser_ID": "",
    "WebPassword_ID": "",
    "WebOTP_ID": "",
    "WebGenericField1_ID": "",
    "WebGenericField2_ID": "",
    "WebGenericField3_ID": "",
    "WebGenericField4_ID": "",
    "WebGenericField5_ID": "",
    "WebGenericField6_ID": "",
    "WebGenericField7_ID": "",
    "WebGenericField8_ID": "",
    "WebGenericField9_ID": "",
    "WebGenericField10_ID": ""
}
]

Note: If the password record being updated is 'Managed', in that it is enabled to perform password resets, then the HTTP Response will not return the full password object, as no data will change for the record until processed from the Password Resets Queue. Instead, the following will be returned:

# Response
HTTP/1.1 200          
[
{
    "PasswordID": 46411,
    "Status": "Password Queued for Reset(s). Check auditing data, or UI for results.",
    "CurrentPassword": "StenS-Lun#3$2^yc",
    "NewPassword": "JENN-ZHn#3+A^yc"
}
]

In addition to updating fields for the Password objects, there are also a few options which can be used to perform certain actions:

GeneratePassword

Data Type: Boolean

Description: If set to true, a newly generated random password will be created based on the Password Generator options associated with the Password List. If the Password List is set to use the user's Password Generator options, the Default Password Generator options will be used instead.

GenerateGenFieldPassword

Data Type: Boolean

Description: If set to true, any 'Generic Fields' which you have set to be of type 'Password' will have a newly generated random password assigned to it. If the Password List or Generic Field is set to use the user's Password Generator options, the Default Password Generator options will be used instead.

PasswordResetEnabled

Data Type: Boolean

Description: This option will enable the account to perform Password Resets. To do this, the Password List the password record belongs to, must also have this option set.

EnablePasswordResetSchedule

Data Type: Boolean

Description: If you want to specify a regular schedule for automatically resetting the value of the Password, you need to enable this option.

PasswordResetSchedule

Data Type: String

Description: This field allows you to set the schedule for automatic password changes. Specify values in the format of 23:10, or 04:00, etc.

AddDaysToExpiryDate

Data Type: Integer

Description: Provides the default value for adding (x) number of days to the ExpiryDate field for all new password records added to the Password List.

Note: This field has been deprecated. Please use the fields AddToExpiryDate and AddToExpiryDateInterval below instead.

AddToExpiryDate

Data Type: Integer

Description: Provides the default value for adding (x) number of days or months to the ExpiryDate field for all new password records added to the Password List. Use the field AddToExpiryDateInterval below to specify Days or Months.

AddToExpiryDateInterval

Data Type: String

Description: Specify Days (default) or Months in conjunction with the field AddToExpiryDate above, to add the require time interval to the Expiry Date field once a password reset has occurred.

ScriptID

Data Type: Integer

Description: Most accounts require a Password Reset Script to be assigned to them, with the only exception being Active Directory Accounts - not to specify this field for AD Accounts. To look up the values of the ScriptID's, this can be done by using the 'Toggle ID Column Visibility' button on the Password Reset Scripts screens in Passwordstate.

PrivilegedAccountID

Data Type: Integer

Description: Some Password Reset Scripts also require a Privileged Account Credential to be associated with the Password record, to initiate connection and perform the reset. Requirements for Privileged Accounts are documented in the User Manual, under the KB Article section. To look up the value of PrivilgedAccountID's, this can be done on the screen Administration -> Passwordstate Administration -> Privileged Account Credentials.

HeartbeatEnabled

Data Type: Boolean

Description: If you want to enable the record to perform regular account heartbeat status update, then set this field to True.

HeartbeatSchedule

Data Type: String

Description: This field allows you to set the schedule for the account heartbeat status update. Specify values in the format of 23:10, or 04:00, etc.

ValidationScriptID

Data Type: Integer

Description: When enabling Account Heartbeat, you must associate the correct Password Validation Script to the record (all account types require a Validation Script to be selected). To look up the values of the ValidationScriptID's, this can be done by using the 'Toggle ID Column Visibility' button on the Password Validation Scripts screens in Passwordstate.

HostName

Data Type: String

Description: If the record relates to account on a Host, then you must specify the Host Name here, as it is stored on the Hosts screen in Passwordstate.

ADDomainNetBIOS

Data Type: String

Description: If the record relates to an Active Directory account, then you must specify the Active Directory NetBIOS value here, as it is stored on the Administration -> Passwordstate Administration -> Active Directory Domains screen in Passwordstate.

ValidatewithPrivAccount

Data Type: Boolean

Description: This field is only used for Linux accounts, and when set to True, the Privileged Account Credential will be used for Authentication when performing Account Heartbeats - useful for accounts like root which generally are not allowed to be used for SSH.

OTPUri

Data Type: String (NA)

Description: A valid URi for an OTP field e.g. otpauth://totp/Example:alice@google.com?secret=XBSW23DPAHPK3PXP&issuer=Example