Update account

This method updates an existing account's details.

Make sure there are no spaces in the URL.

The following characters are not supported in URL values: + & %
If the URL includes a dot (.), add a forward slash (/) at the end of the URL. For example: api/Safes/MySafe/Members/user@cyber.com/

Select the method you want to use:

2nd gen API (recommended)

It is not mandatory to send all the account’s details. Any changed values sent in the request will be updated. All other properties values will remain the same.

You can do the following:

Replace the existing value of a property
Remove property from the account
Add property to the account

When sending several operations on the same property, only the last operation will affect the property.

URL

https://<IIS_Server_Ip>/PasswordVault/API/Accounts/{AccountID}/

The following mandatory value is required in the URL:

Parameter	AccountID
Type	String
Description	The unique ID of the account to update. This is retrieved by the Get Account Service.
Valid values	Account ID

Resource information

HTTP method	Patch
Content type	application/json

Header parameter

Parameter	Description
Authorization	The token that identifies the session, encoded in BASE 64. See Authentication. Type: String Mandatory: Yes Default value: None

Body parameters

[{ "op": "replace", "path": "/address", "value": "10.10.27.254"},
  { "op": "replace", "path": "/secretManagement/automaticManagementEnabled", "value": "false"}]

Operations:

Parameter	Value
Type	string
Description	The updated property value
Valid values	Property value
Parameter	path
Type	String
Description	The path of the property name. The list of possible properties are described in the table below.
Valid values	Property name. Example: `"\address"`
Parameter	Op
Type	String
Description	The allowed operations to perform on the properties.
Valid values	Replace (to replace the existing value of that property) Remove (to remove the property from the account) Add (to add that property to the account)

Available properties to update:

Parameter

Name

Type

string

Description

The name of the account.

Valid values

Account name

Parameter

address

Type

String

Description

The name or address of the machine where the account is used.

Valid values

vDNS/IP/URL where the account is managed

Parameter

userName

Type

String

Description

Account user's name.

Valid values

User name

Parameter

platformId

Type

string

Description

The platform assigned to this account.

Valid values

Valid platform IDs, example: WinServerLocal

Parameter

userName

Type

string

Description

Account user's name.

Valid values

User name

Parameter

platformAccountProperties

Type

string

Description

Object containing key-value pairs to associate with the account, as defined by the account platform. These properties are validated against the mandatory and optional properties of the specified platform's definition. Optional properties that do not exist on the account will not be returned here.

Valid values

example: {"Location": "IT", "OwnerName": "MSSPAdmin"}

secretManagement

Parameter	automaticManagementEnabled
Type	Boolean
Description	Whether the account secret is automatically managed by the CPM.
Default	true
Valid values	true, false
Parameter	manualManagementReason
Type	string
Description	Reason for disabling automatic secret management.
Valid values	Reason.
Parameter	status
Type	string
Description	Account management status.
Valid values	inProcess, succeeded, failed, partiallySucceeded
Parameter	lastModifiedDateTime
Type	string
Description	Last modified date of the account.
Valid values	date-time
Parameter	lastReconciledDateTime
Type	string
Description	Last reconciled date of the account.
Valid values	date-time
Parameter	lastVerifiedDateTime
Type	string
Description	Last verified date of the account.
Valid values	date-time

remoteMachinesAccess

Parameter	remoteMachines
Type	string
Description	List of remote machines, separated by semicolons. Example: server1.cyberark.com;server2.cyberark.com
Valid values	List of machines.
Parameter	accessRestrictedToRemoteMachines
Type	Boolean
Description	Whether or not to restrict access only to specified remote machines
Valid values	true, false

Examples

{ "op": "replace", "path": "/address", "value": "NewAddress"}
{ "op": "add", "path": "/platformaccountproperties/port", "value": "456"}
{ "op": "remove", "path": "/secretmanagement/manualmanagementreason"}

Result

{
  "id": "string",
  "name": "string",
  "address": "string",
  "userName": "string",
  "platformId": "string",
  "safeName": "string",
  "secretType": "key",
  "platformAccountProperties": {},
  "secretManagement": {
    "automaticManagementEnabled": true,
    "manualManagementReason": "string",
    "status": "inProcess",
    "lastModifiedTime": 0,
    "lastReconciledTime": 0,
    "lastVerifiedTime": 0
  },
  "remoteMachinesAccess": {
    "remoteMachines": "string",
    "accessRestrictedToRemoteMachines": true
  },
  "createdTime": 0
}

Parameter

Type

string

Description

The ID of the account.

Valid values

Valid account ID

Parameter

safeName

Type

string

Description

The Safe where the account is stored.

Valid values

Safe name

Parameter

platformId

Type

string

Description

The platform assigned to this account.

Valid values

Valid platform IDs, example: WinServerLocal

Parameter

address

Type

string

Description

The name or address of the machine where the account is used.

Valid values

vDNS/IP/URL where the account is managed

Parameter

name

Type

string

Description

The name of the account.

Valid values

Account name

Parameter

secretType

Type

string

Description

The type of password.

Valid values

password, key

Parameter

userName

Type

string

Description

Account user's name.

Valid values

User name

Parameter

platformAccountProperties

Type

string

Description

Valid values

example: {"Location": "IT", "OwnerName": "MSSPAdmin"}

secretManagement

Parameter	automaticManagementEnabled
Type	Boolean
Description	Whether the account secret is automatically managed by the CPM.
Default	true
Valid values	true, false
Parameter	manualManagementReason
Type	string
Description	Reason for disabling automatic secret management.
Valid values	Reason.
Parameter	status
Type	string
Description	Account management status.
Valid values	inProcess, succeeded, failed, partiallySucceeded
Parameter	lastModifiedDateTime
Type	string
Description	Last modified date of the account.
Valid values	date-time
Parameter	lastReconciledDateTime
Type	string
Description	Last reconciled date of the account.
Valid values	date-time
Parameter	lastVerifiedDateTime
Type	string
Description	Last verified date of the account.
Valid values	date-time

remoteMachinesAccess

Parameter	remoteMachines
Type	string
Description	List of remote machines, separated by semicolons. Example: server1.cyberark.com;server2.cyberark.com
Valid values	List of machines.
Parameter	accessRestrictedToRemoteMachines
Type	Boolean
Description	Whether or not to restrict access only to specified remote machines
Valid values	true, false

Parameter

createdDateTime

Type

string

Description

Date and time account was created.

Valid values

date-time

1st gen API

In order to execute this web service, all the account’s details must be entered in the web service request. If existing account properties are not sent as part of the request, the properties will be removed from the account. Any changed values sent in the request will be updated. All other properties values will remain the same.

When you change the name or folder of a service account that has multiple dependencies (usages), the connection between it and its dependencies will be automatically maintained.

In addition, when you change the name or a folder of an account that is linked to another account, whether logon, reconciliation or verification, links will be automatically updated.

Limitations

This web service has the following limitations:

■

Dependencies (usages) cannot be updated.

■

Accounts that do not have a policy ID cannot be updated.

Permissions

To update account properties, Safe members require the following permission:

■

Update password properties

To rename accounts, Safe members require the following permission:

■

Rename accounts

To move accounts to a different folder, Safe members require the following permission:

■

Move accounts/folders

URL

https://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Accounts/{AccountID}

The following mandatory value is required in the URL:

Parameter	AccountID
Type	String
Description	The unique ID of the account to update. This is retrieved by the Get Account Service.
Valid values	Account ID

Resource information

HTTP method	PUT
Content type	application/json

Header parameter

Parameter	Description
Authorization	The token that identifies the session, encoded in BASE 64. See Authentication. Type: String Mandatory: Yes Default value: None

Query parameters

The following parameters can be specified in the URL to filter the result:

Parameter	Folder
Type	String
Description	The folder where the account is stored.
Valid values	Folder name
Parameter	AccountName
Type	String
Description	The name of the account to update. Make sure the account name meets your enterprise account policy specifications.
Valid values	Account name
Parameter	DeviceType
Type
Description	The device type to update. Make sure you specify all required parameters. Different device types require different parameters.
Valid values	Device type
Parameter	PlatformID
Type	String
Description	The Platform ID of the new platform to assign to this account. Make sure you specify all required parameters. Different platforms require different parameters.
Valid values	Platform ID
Parameter	Address
Type	String
Description	The new name or address of the machine where the account will be used.
Valid values	Machine name or address
Parameter	UserName
Type	String
Description	The updated name of the user who will use the account on the target machine.
Valid values	User name on the target machine
Parameter	GroupName
Type	String
Description	The name of the group with which the account is associated. To create a new group, specify the group platform ID in the GroupPlatformID property, then specify the group name. The group will then be created automatically.
Valid values	Account group name
Parameter	GroupPlatformID
Type	String
Description	GroupPlatformID is required when you want to move an account to a new group.
Valid values	Group platform ID
Parameter	Properties
Type	List
Description	List of name=value pairs. Bind this list together with square brackets [ ] as shown in the example below.
Valid values	Property name and value

Examples

In the following example all properties were sent with the original value except for the account address, which will be updated from 1.1.1.1 to 10.10.10.10:

{

"Accounts":

 {

 "Folder":"Root",

 "AccountName":"Operating System-WinDesktopLocal-1.1.1.1-Administrator",

 "PlatformID":"WinDesktopLocal",

 "DeviceType":"Operating System",

 "Address":"10.10.10.10",

 "UserName":"Administrator"

 }

}

In the following example, a new account group name was entered to replace an existing account group name in the optional GroupName field:

{

"Accounts":

 {

 "Folder":"Root",

 "AccountName":"Operating System-WinDesktopLocal- 1.1.1.1-Administrator",

 "PlatformID":"WinDesktopLocal",

 "DeviceType":"Operating System",

 "Address":"10.10.10.10",

 "UserName":"Administrator",

 "GroupName":"WindowsAccountGroup"

 }

}

In the following example, department and geographical location properties are added to an existing account with properties:

{

 "Accounts":

 {

 "Folder":"Root",

 "AccountName":"Operating System-WinDesktopLocal-1.1.1.1-Administrator",

 "PlatformID":"WinDesktopLocal",

 "DeviceType":"Operating System",

 "Address":"10.10.10.10",

 "UserName":"Administrator",

 "GroupName":"WindowsAccountGroup",

 "Properties":[{

 "Key":"Department", "Value":"Finance"},

 {"Key":"GeoLocation", "Value":"UK"}]

 }

}

Body parameters

None

Result

{

}

Return codes

For a complete list of return codes, see Return Codes.