Privileged Account Security Web Services SDK Implementation Guide PDF

Privileged Account Security
Web Services SDK

Implementation Guide
Version 10.3
2
Important Notice
Conditions and Restrictions
This guide is delivered subject to the following conditions and restrictions:
This guide contains proprietary information and ideas belonging to CyberArk Software Ltd. which
are supplied solely for the purpose of assisting explicitly and properly authorized users of the
CyberArk software.
No part of its contents may be used for any other purpose, disclosed to any person or firm or
reproduced by any means, electronic and mechanical, without the express prior written
permission of CyberArk Software Ltd.
The software described in this document is furnished under a license. The software may be used
or copied only in accordance with the terms of that agreement.
Information in this document, including the text and graphics which are made available for the
purpose of illustration and reference only, is subject to change without notice. Corporate and
individual names and data used in examples herein are fictitious unless otherwise noted.
Third party components used in the CyberArk software may be subject to applicable terms and
conditions.
Acknowledgements
This product includes software developed by the OpenSSL Project for use in the OpenSSL
Toolkit (http://www.openssl.org/).
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).
This product includes software written by Tim Hudson (tjh@cryptsoft.com).
This product includes software written by Ian F. Darwin.
This product includes software developed by the ICU Project (http://site.icu-project.org/)
Copyright © 1995-2009 International Business Machines Corporation and other. All rights
reserved.
Copyright
© 2000-2018 CyberArk Software Ltd. All rights reserved.
CyberArk®, the CyberArk logo, and all other names and logos that appear in this Guide are
trademarks of CyberArk Software Ltd. and their respective owners.
Information in this document is subject to change without notice.
PASWS-10-3-0-1

3 Table of Contents
Table of Contents
REST Web Services 6

What’s New 7
Onboarding rules 7
PSM connections 7
Platforms 7
Introduction 8
SDK Supported Platforms 9
Using the PAS Web Services SDK 9
Configuring PAS REST API to work with HTTPS 10
Return Codes 11
API Commands 12
Authentication 13
CyberArk Authentication 13
SAML Authentication 17
Shared Logon Authentication 19
Managing Users' Authorized Public SSH Keys 25
Server 31
Verify 31
Logo 33
Server 34
Users 36
Add User 36
Update User 39
Delete User 43
Logged on User Details 44
Get User Details 45
Activate User 47
Add User to Group 50
Safes 52
List Safes 52
Get Safe Details 53
Add Safe 55
Update Safe 57
Delete Safe 59
Search for a Safe 61
Get Safe Account Groups 62
Safe Members 64
List Safe Members 64
Add Safe Member 65
Update Safe Member 72
Delete Safe Member 78
Platforms 80
Get Platform Details 80
Import Platform 81
Accounts 84

Table of Contents 4
Add Account 84
Add Pending Account 88
Delete Account 93
Get Account Value 94
Get Password Value (from v10) 95
Change Credentials 98
Change credentials immediately 100
Change Credentials and Set Next Password 102
Change Credentials in the Vault 106
Verify credentials (up to v9.9.5) 108
Verify credentials (from v9.10) 109
Reconcile credentials 111
Get Account Details 113
Update Account Details 116
Check-in an exclusive account 121
List Activity by ID 122
Account Groups 125
Add Account Group 125
Add Account to Account Group 127
Get Account Group by Safe 128
Get Account Group Members 130
Delete Member from Account Group 132
Policy/ACL 134
List Policy/ACL 134
Add Policy/ACL 135
Delete Policy/ACL 138
Account/ACL 140
List Account/ACL 140
Add Account/ACL 142
Delete Account ACL 145
Onboarding Rules 147
Add Automatic Onboarding Rule 147
Delete Automatic Onboarding Rule 150
Get Automatic Onboarding Rules 152
My Requests 156
Create a Request 156
Get My Requests 167
Delete My Request 173
Get Details of My Requests 174
Confirm Requests 182
Get Incoming Request List 182
Get Details of a Request for Confirmation 188
Confirm Request 196
Reject Request 198
Connections 200
Connect Through PSM 200
Import Connection Component 204
Applications 207
List Applications 207
List a Specific Application 209
Add Application 211

5 Table of Contents
List all Authentication Methods of a Specific Application 214

Delete a Specific Application 215
Add Authentication 216
Delete a Specific Authentication 222
Monitor Sessions 224
Get Recordings 224
Get Live Sessions 232
Terminate a Session 242
Suspend/Resume a Session 245
Event Security 248
Get Security Events 248
System Health 255
System Details 255
System Summary 257
Usage Examples 261
Example 1: Listing Account ACLs 261
Example 2: Adding an Application/Authentication 267
Troubleshooting 272

6
REST Web Services
The Privileged Account Security Web Services enable you to create, list, modify and
delete entities in Privileged Account Security solution from within programs and scripts.
In this section:
What’s New

Privileged Account Security Web Services SDK Implementation Guide 7
What’s New
The following web services are now available:
Onboarding rules
Onboarding Rules enable you to create and manage predefined rules that automatically
onboard newly discovered accounts. This minimizes the time it takes to onboard and
securely manage accounts, reduces the time spent on reviewing pending accounts, and
prevents human errors that may occur during manual onboarding.
After accounts are discovered, they are automatically filtered by the onboarding rules and
provisioned in the Vault. Accounts that cannot be filtered by any of the rules are added to
the Pending Accounts list in the PVWA and can be reviewed and onboarded manually.
Add Onboarding Rule
Delete Onboarding Rule
Get Automatic Onboarding Rules, page 152
PSM connections
You can connect to an account through PSM using through RDP or a PSM gateway
(HTML5), as defined in the PVWA .
Connect Through PSM, page 200
Platforms
Administrators can import new platforms to associate with accounts.
Import Platform, page 81

8
Introduction
The PAS Web Services is a RESTful API that enables users to create, list, modify and
delete entities in Privileged Account Security solution from within programs and scripts.
The main purpose of the PAS Web Services is to automate tasks that are usually
performed manually using the UI, and to incorporate them into system and account-
provisioning scripts.
The PAS Web Services are installed as part of the PVWA installation, and can be used
immediately without any additional configuration. Make sure your CyberArk license
enables you to use the CyberArk PAS SDK. For more information, contact your
CyberArk support representative.

SDK Supported Platforms

The PAS Web Services SDK is a RESTful API that can be invoked by any RESTful client
for various programming and scripting environments, including Java, C#, Perl, PHP,
Python and Ruby.
Using the PAS Web Services SDK

The PAS Web Services SDK enables you to perform activities on PAS objects via a
REST Web Service interface. Each PAS object has its own URL path in the PVWA
website that can be accessed using the relevant HTTP/S request verb.
Note:
Although you can use HTTP requests, for security reasons, it is recommended
to use HTTPS. For more information about configuring the REST Web Service
API for HTTPS, refer to Configuring PAS REST API to work with HTTPS, page 10.
For example, to get a list of all privileged commands (OPM rules) associated with a
specific account, access the privileged commands path of that account with an HTTP/S
GET request, using the following format:
https://<IIS_Server_
Ip>/PasswordVault/WebServices/PIMServices.svc/Account/<AccountAdress>|<Accou
ntUserName>|<AccountPolicyId>/PrivilegedCommands
Example:
https://10.10.10.10/PasswordVault/WebServices/PIMServices.svc/Account/MyComp|root|
UnixSSH/PrivilegedCommands
As a result of the above request, a list of all privileged commands associated with the root
user of the machine MyComp appears, in JSON format.
Every HTTP/S request must contain an HTTP/S header field named Authorization that
contains the value of a session token received from the Logon method.
If you have an SSH key license, you can add new SSH keys and pending SSH keys to
the Vault as well as accounts. For more information, contact your CyberArk
representative.
The PAS Web Services can be accessed with any tool or language that enables you to
create HTTP/S requests and handle HTTP/S responses. For more information, refer to
the C# and Java examples in Usage Examples.
For information about the codes returned by the REST web services API commands,
refer to Return Codes.

10 Configuring PAS REST API to work with HTTPS
Configuring PAS REST API to work with HTTPS

1. In the PasswordVault installation folder, open the web.config file.
2. In the service tag, add bindingConfiguration="httpsBinding", as shown in the
following example:
Example:
<service behaviorConfiguration="defaultBehavior"
name="CyberArk.WSAuthentication.Cyberark.CyberArkAuthenticationSe
rvice">
<endpoint name="AuthEndpoint" address="/"
behaviorConfiguration="web" binding="webHttpBinding"
bindingConfiguration="httpsBinding"
contract="CyberArk.WSAuthentication.Cyberark.ICyberArkAuthenticat
ionService" />
</service>
<service behaviorConfiguration="defaultBehavior"
name="CyberArk.PasswordVault.WebServices.WF.PIMServices">
<endpoint name="PIMEndpoint" address="/"
behaviorConfiguration="web" binding="webHttpBinding"
bindingConfiguration="httpsBinding"
contract="CyberArk.PasswordVault.WebServices.WF.IPIMServices" />
</service>
3. Save the web.config file and close it.

Return Codes
The following table lists all the return codes that are returned from the REST Web
Services API.
Return Code
Description
Code Number
Success 200 The request succeeded. The actual response will depend
on the request method used.
Created 201 The request was fulfilled and resulted in a new resource
being created.
Bad request 400 The request could not be understood by the server due to
incorrect syntax.
Unauthorized 401 The request requires user authentication.
Forbidden 403 The server received and understood the request, but will not
fulfill it. Authorization will not help and the request MUST
NOT be repeated.
Not Found 404 The server did not find anything that matches the Request-
URI. No indication is given of whether the condition is
temporary or permanent.
Conflict 409 The request could not be completed due to a conflict with
the current state of the resource.
Internal 500 The server encountered an unexpected condition which

Server Error prevented it from fulfilling the request.

12
API Commands
The Privileged Account Security API commands enable you to implement CyberArk’s
Web Services SDK. The following sections describe how to use them and give samples
that show typical implementations.
Note:
For every Web Services call except for Logon, the request must include an
HTTP/S header field named Authorization, containing the value of a session
token received from the Logon activity.

Authentication
CyberArk Authentication
CyberArk authentication is based on a user’s location in the Vault. Each user has their
own token that can be identified in the Vault with different credentials.
You can use the following web services for CyberArk authentication:
Logon
Logoff
Logon
This method authenticates a user to the Vault and returns a token that can be used in subsequent
web services calls. In addition, this method allows you to set a new password.
Users can authenticate using CyberArk, LDAP or RADIUS authentication.
This method is demonstrated in the sample code.
URL
Ip>/PasswordVault/WebServices/auth/Cyberark/CyberArkAuthenticationService.svc/Logo
n
Resource Information
HTTP method POST
Content type application/json
Body parameters
{
"username":"<user_name>",
"password":"<password>",
"newPassword":"<password>",
"useRadiusAuthentication":"<bool>",
"connectionNumber":"<integer>"
}

14 Authentication
The Logon syntax has these parts:

Parameter username
Type String
Description The name of the user who will logon to the Vault.
Mandatory Yes
Default None
Parameter password
Type String
Description The password of the user.
Mandatory Yes
Default None
Parameter newPassword
Type String
Description The new password of the user. This parameter is optional, and enables you
to change a password.
Mandatory No
Default None
Parameter useRadiusAuthentication
Type Boolean
Description Whether or not users will be authenticated via a RADIUS server.
Note:
The RADIUS challenge response is currently limited to 512
characters.
Valid values true/false
Mandatory No
Default false
Parameter connectionNumber
Type Integer
Description In order to allow more than one connection for the same user
simultaneously, each request should be sent with a different
'connectionNumber'.
Valid values 1-100
Mandatory No
Default None

Result
{
"CyberArkLogonResult":"<session token>"
}
Parameter CyberArkLogonResult
Type Long
Description A session token.

16 Authentication
Logoff
This method logs off the user and removes the Vault session. It is demonstrated in the
sample code.
URL
Ip>/PasswordVault/WebServices/auth/Cyberark/CyberArkAuthenticationService.svc/Logo
ff
HTTP method POST
Header parameter
Parameter Authorization
Type String
Description The token that identifies the session.
Valid values None.
Body parameters
None
Result
{
}
Return Codes
Status code 200
Description OK

SAML Authentication
You can use the following web services for SAML authentication:
■ Logon
■ Logoff
Logon
This method authenticates a user to the Vault using SAML authentication and returns a
token that can be used in subsequent web services calls.
URL
Ip>/PasswordVault/WebServices/auth/SAML/SAMLAuthenticationService.svc/Logon
HTTP method POST
Header parameter
Type String
Description The token that identifies the session, encoded in BASE 64.
Valid values None
Body parameters
None
Result
{
"CyberArkLogonResult":"<session token>"
}

18 Authentication
Logoff
This method logs off the user and removes the Vault session. This web service is used to
log off when the user authenticated with SAML authentication.
URL
Ip>/PasswordVault/WebServices/auth/SAML/SAMLAuthenticationService.svc/Logoff
HTTP method POST
Header parameter
Type String
Valid values None
Body parameters
None
Result
{
}
Return Codes
Status code 200
Description OK

Shared Logon Authentication

Shared authentication is based on a user credential file that is stored in the PVWA web
server. During shared authentication, only the user defined in the credential file can logon
to the PVWA, but multiple users can use the logon token.
This type of authentication requires the application using the REST services to manage
the users as the Vault can't identify which specific user performs each action.
Multiple concurrent connections can be created using the same token, without affecting
each other.
The shared user is defined in a user credential file, whose location is specified in the
WSCredentialFile parameter, in the appsettings section of the PVWA web.config file:
<add key="WSCredentialFile" value="C:\CyberArk\Password Vault Web
Access\CredFiles\WSUser.ini"/>
Make sure that this user can access the the PVWA interface.
Make sure the user only has the permissions in the Vault that they require.
For information about securing communication when using the SDK, refer to the
following:
Securing Communication between Applications and the REST Web Services
Configuring Client Authentication via Client Certificates
You can use the following web services for Shared Logon authentication:
Logon
Logoff
Securing Communication between Applications and the REST Web

Services
It is recommended to secure connections between the requesting application and the
REST Web Services when using Shared Logon Authentication, using Client
Authentication.
In addition to SSL, use Client Authentication to authenticate the requesting application
using a client certificate.

20 Authentication
Configuring Client Authentication via Client Certificates

This procedure enables client side authentication of the requesting application against
the REST Web Services, using a client certificate.
To configure Client authentication via Client certificates
For IIS 6.0
For IIS 7.0
For IIS 6.0
1. Make sure that a server certificate has been generated for the web server where the
PVWA is installed.
2. In the PVWA Virtual Directory, change the Secure Communication settings:
a. Run inetmgr, select Web Sites, then select the website where the PVWA runs.
b. Right-click PVWA , then select Properties; the Properties window appears.
c. In the Directory Security tab, in the Secure Communications area, click Edit;
the Secure Communication window appears.
d. Select the following:
Require secure channel (SSL)
Accept client certificates
Note: If you use a client certificate, select Require client certificates instead of
Accept Client Certificates.
e. Click OK to save the Secure Communications settings; the Inheritance Overrides

window appears. This window enables you to configure the security settings to
apply the selected security settings to the listed child nodes.

f. Do not select any child nodes from the list. Click OK.
3. In the PVWA Web Services folder, change the Secure Communication settings:
a. Expand PVWA , and then expand WebServices.
b. Expand auth, and then right-click Shared; the Shared Properties window
appears.
c. In the Directory Security tab, in the Secure Communications area, click Edit;
the authentication settings for the Shared folder are displayed.
d. In Client certificates, select Require client certificates, then click OK.
e. Run iisreset.
For IIS 7.0

1. Make sure that a server certificate has been generated for the web server where the
PVWA is installed.
2. In the PVWA Virtual Directory, change the Secure Communication settings:
a. Run inetmgr, select Sites, then select the website where the PVWA runs.

22 Authentication
b. Select SSL Settings, the SSL Setting window appears.

c. Select the following:
Require SSL
Accept – This configures the IIS to accept Client Certificates.
Note: If you use a client certificate, select Require instead of Accept.
d. Click Apply to save the Secure Communications settings;

3. In the PVWA Web Services folder, change the Secure Communication settings:
a. Expand PVWA , and then expand WebServices.
b. Expand auth, and then select Shared.
c. Select SSL Settings, the SSL Setting window appears,
d. Select the following:
Require SSL
Require – This configures the IIS to require Client Certificates.
e. Click Apply to save the Secure Communications settings;
4. Run iisreset.

Logon
This method authenticates to the Vault with a shared webservices user and returns a
token that will be used in subsequent web services calls. It is demonstrated in sample
code.
This is supported for CyberArk authentication only, and not for third party authentication.
URL
Ip>/PasswordVault/WebServices/auth/Shared/RestfulAuthenticationService.svc/Logon
HTTP method POST
Body parameters
None
Result
{
"LogonResult":"<session token>"
}

24 Authentication
Logoff
This method logs off the shared user and removes the Vault session.
URL
https://<IIS_Server_Ip>/PasswordVault/WebServices/auth/
Shared/RestfulAuthenticationService.svc/Logoff
HTTP method POST
Header parameter
Type String
Valid values None
Body parameters
None
Result
{
}
Return Codes
Status code 200
Description OK

Managing Users' Authorized Public SSH Keys

The following methods enable you to manage users' authorized public SSH keys and
allow them to authenticate to the PSMP with SSH key authentication:
Add a Public SSH Key
Get Public SSH Keys
Delete Public SSH Key
Add a Public SSH Key

This method adds an authorized public SSH key for a specific user in the Vault, allowing them to
authenticate to the Vault through PSMP using a corresponding private SSH key.
The user who runs this web service requires the following permission in the Vault:
Reset Users' Passwords
In addition, the user who runs this web service must be in the same Vault Location or higher as
the user whose public SSH keys are added.
Note:
A user cannot manage their own public SSH keys.
URL
Note:
Make sure there are no spaces in the URL.
The following characters are not supported in URL values: + & %
Ip>/PasswordVault/WebServices/PIMServices.svc/Users/
{UserName}/AuthenticationMethods/SSHKeyAuthentication/AuthorizedKeys
The following mandatory value is required in the URL:

Parameter UserName
Type String
Description The name of the user whose public SSH keys will be added.
Note:
This username is not case-sensitive.
Specify the name of any user in the Vault.
Valid values Vault user name

26 Authentication
HTTP method POST
Header parameter
Type String
Valid values A session token that was returned from the “Logon” method.
Body parameters
Note:
The public SSH key must be included as a JSON object in the request body.
{
"PublicSSHKey":"<public-key>"
}
Parameter PublicSSHKey
Type String
Description The content of the public SSH key as it appears in the authorized_keys file.
This parameter is required.
Mandatory Yes
Valid values A public SSH key.

This key must not include new lines ('\n').
Do not include options such as "command", as they are not supported
when authenticating through PSMP.
This key can only include comments in English.
Result
"AddUserAuthorizedKeyResult":
{
"KeyID":"<key-id>",

Return Codes
Status code 201
Description The public SSH key was added successfully

28 Authentication
Get Public SSH Keys

This method retrieves all public SSH keys that are authorized for a specific user.
the user whose public SSH keys are retrieved.
Note:
URL
Note:
{UserName}/AuthenticationMethods/SSHKeyAuthentication/AuthorizedKeys

Parameter UserName
Type String
Description The name of the user whose public SSH keys will be retrieved.
Note:
HTTP method GET
Header parameter
Type String

Body parameters
None
Result
{
"GetUserAuthorizedKeysResult":
[
{
"KeyID":"<key-id>",
},
{
"KeyID":"<key-id>",
}
]
}
Return Codes
Status code 200
Description OK
Delete Public SSH Key

This method deletes an authorized public SSH key for a specific user in the Vault, preventing
them from authenticating to the Vault through PSMP using a corresponding private SSH key.
the user whose public SSH keys are deleted.
Note:
URL
Note:
{UserName}/AuthenticationMethods/SSHKeyAuthentication/AuthorizedKeys/

30 Authentication
{KeyID}

Parameter UserName
Type String
Description The name of the user whose public SSH keys will be added.
Note:
Parameter KeyID
Type String
Description The ID of the public SSH key to delete.
Valid values The key ID, as returned from the GET method.
HTTP method DELETE
Header parameter
Type String
Body parameters
None
Result
None
Return Codes
Status code 200
Description The public SSH key was deleted successfully

Server
Verify
This method returns the display name of the Vault configured in the
ServerDisplayName configuration parameter.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Verify
HTTP method GET
Body parameters
None
Result
{
"ServerName":"<Vault_Name>",
"ServerID":"<Unique Vault_ID>",
"ApplicationName":"<PasswordVault>",
"AuthenticationMethods":"[{"Id":"authmethod","Enabled/Disabled":"true/false"}]"
}
Parameter ServerName
Type String
Description The display name of the Vault configured in the ServerDisplayName

configuration parameter.
Parameter ServerID

32 Server
Type Integer
Description The Vault's ID.
Parameter ApplicationName
Type String
Description The name of the application used. Possible values: "PasswordVault".
Parameter AuthenticationMethods
Type String
Description The authentication methods that can be used to authenticate to the Vault,
and whether or not they are enabled. For example, "windows".

Logo
This method returns the configuration of the logo that will be displayed in the CyberArk
SafeShare logon screen and account settings.
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Logo? type=
{ImageType}

Parameter ImageType
Type String
Description The requested logo type: Square or Watermark.
Default Square
HTTP method GET
Body parameters
None
Result
Status Stream

34 Server
Server
This method returns the display name of the Vault configured in the
ServerDisplayName configuration parameter.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Server
HTTP method GET
Header parameter
Type String
Body parameters
None
Result
{
"ServerName":"<Vault_Name>" ,
"ExternalVersion":"<ExternalVersion>",
"InternalVersion":"<InternalVersion>"
}
Parameter ServerName
Type String
Description The display name of the Vault configured in the ServerDisplayName

configuration parameter.
Parameter ExternalVersion
Type String
Description The external version of the Vault.
Parameter InternalVersion
Type String
Description The internal version of the Vault.

36 Users
Users
Add User
This method adds a new user to the Vault.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Users
HTTP method POST
Header parameter
Type String
Body parameters
{
"UserName":"<string>",
"InitialPassword":"<string>",
"Email":"<string>",
"FirstName":"<string>",
"LastName":"<string>",
"ChangePasswordOnTheNextLogon":<bool>,
"ExpiryDate":"<string>",
"UserTypeName":"<string>",
"Disabled":<bool>,
"Location":"<string>"

Parameter UserName
Type String
Description The name of the user who will be added.
Default None
Parameter InitialPassword
Type String
Description The password that the user will use to log on the first time. This password
must meet the password policy requirements.
Default None
Parameter Email
Type String
Description The user’s email address.
Default None
Parameter FirstName
Type String
Description The user’s first name.
Default None
Parameter LastName
Type String
Description The user’s last name.
Default None
Parameter ChangePasswordOnTheNextLogon
Type Boolean
Description Whether or not the user must change their password when they log on for
the first time.
Default true
Parameter ExpiryDate
Type Date Time
Description The date when the user will expire and become disabled.
Default Never

38 Users
Parameter UserTypeName
Type String
Description The type of user to create.
Default EPVUser
Parameter Disabled
Type Boolean
Description Whether or not the user will be created as a disabled user.
Default false
Parameter Location
Type String
Description The Vault Location where the user will be created.
Default Root
Result
{
"Email":"<string>",
"Source":"<string>",
"Expired":"<bool>",
"Disabled":"<bool>",
"AgentUser":"<bool>",
"Suspended":"<bool>"
"Location":"<Vault Location>"
"ExpiryDate":"<date>"
}

Update User
This method updates an existing Vault user.
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Users/{UserName}

Parameter UserName (mandatory)
Type String
Description The name of the user to update.
HTTP method PUT
Header parameter
Type String
Body parameters
{
"NewPassword":"<string>",
"Email":"<string>",
"Disabled":<bool>,

40 Users
"Location":"<string>”
}
Parameter NewPassword (optional)
Type String
Description The user’s updated password. Make sure that this password meets the
password policy requirements.
Default Current value
Parameter Email (optional)
Type String
Parameter FirstName (optional)
Type String
Parameter LastName (optional)
Type String
Parameter ChangePasswordOnTheNextLogon (optional)
Type Boolean
Description Whether or not the user must change their password in their next logon.
Parameter ExpiryDate (optional)
Type DateTime
Description The date and time when the user’s account will expire and become
disabled.
Parameter UserTypeName (optional)
Type String
Description The updated type of user, as specified in the CyberArk license.

Parameter Disabled (optional)
Type Boolean
Description Whether or not the user will be disabled when updated.
Parameter Location (optional)
Type String
Description The new Location of the updated user in the Vault hierarchy
Default -
Result
{
"Email":"<string>",
"Expired":"<string>",
"Suspended":"<bool>",
}
Parameter FirstName
Type String
Parameter LastName
Type String
Parameter UserName
Type String
Description The name of the updated user.

42 Users
Parameter Email
Type String
Parameter Source
Type String
Description Whether the user was created in the PrivateArk Client or the PVWA, or is
an external user who was created from an LDAP directory.
Valid values LDAP/Internal
Type String
Description The new user type of this user, as specified in the CyberArk license.
Parameter ChangePasswordOnTheNextLogon
Type Boolean
Description Whether or not the user will be forced to change their password in their next
logon.
Parameter Expired
Type Boolean
Description Whether or not the user’s password has expired
Type DateTime
Description The date when the user’s account will expire and become disabled.
If the user account will never expire, ‘null’ will be returned.
Parameter Disabled
Type Boolean
Description Whether or not the updated user is disabled.
Parameter Suspended
Type Boolean
Description Whether or not the updated user is suspended.
Parameter AgentUser
Type Boolean
Description Whether or not this user is a gateway user.
Parameter Location
Type String

Description The Location of the updated user in the Vault hierarchy.
Delete User
This method deletes a specific User in the Vault. It is demonstrated in the sample code.
URL
Note:

Parameter UserName
Type String
Description The name of the user to delete.
HTTP method DELETE
Header parameter
Type String
Body parameters
None
Result
{
}

44 Users
Logged on User Details

This method returns user information of the user who is logged on. It is demonstrated in
the sample code.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/User
HTTP method GET
Header parameter
Type String
Body parameters
None
Result
{
"Email":"<string>",
"Expired":"<bool>",
}

Get User Details

This method returns information about a specific User in the Vault. It is demonstrated in the
sample code.
URL
Note:

Parameter UserName
Type String
Description The name of the User for which information is returned.
HTTP method GET
Header parameter
Type String
Body parameters
None
Result
{

46 Users
"Email":"<string>",
"Expired":"<bool>",
}

Activate User
This method activates an existing Vault user who was suspended after entering incorrect
credentials multiple times.
Note:
This method activates a suspended user. It does not activate an inactive user.
URL
Note:

Type String
Description The name of the user to activate.
Default None
HTTP method PUT
Header parameter
Parameter Authorization (mandatory)
Type String
Body parameters

48 Users
}
Parameter Suspended (optional)
Type Boolean
Description Whether or not the user will be activated.
Valid values false
Result
{
"Email":"<string>",
"Expired":"<string>",
"Suspended":"<bool>",
}
Parameter FirstName
Type String
Parameter LastName
Type String
Parameter UserName
Type String
Description The name of the user.
Parameter Email
Type String

Parameter Source
Type String
Description Whether the user was created in the PrivateArk Client or the PVWA, or is
an external user who was created from an LDAP directory.
Valid values LDAP/Internal
Type String
Description The type of the user.
Parameter ChangPasswordOnTheNextLogon
Type Boolean
Description Whether or not the user will be forced to change their password in their next
logon.
Parameter Expired
Type Boolean
Description Whether or not the user’s password has expired
Type DateTime
Description The date when the user’s account will expire and become disabled.
If the user account will never expire, ‘null’ will be returned.
Parameter Disabled
Type Boolean
Description Whether or not the activated user is disabled.
Parameter Suspended
Type Boolean
Description Whether or not the activated user is suspended.
Parameter AgentUser
Type Boolean
Description Whether or not this user is a gateway user.
Parameter Location
Type String
Description The Location of the activated user in the Vault hierarchy.

50 Users
Add User to Group

This method adds a specific user to an existing user group in the Vault.
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Groups/
{GroupName}/Users

Parameter GroupName
Type String
Description The name of the group to which the user will be added.
Valid values Group name
HTTP method POST
Header parameter
Type String
Body parameters
{
"UserName":"<string>"
}

Type String
Description The name of the user who will be added to the specified group.
Default -
Result
{
}
Return Codes
Status code 201

52 Safes
Safes
List Safes
This method returns information about all of the user’s Safes in the Vault. It is demonstrated in the
sample code.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Safes
HTTP method GET
Header parameter
Type String
Body parameters
None
Result
[
{
"Description":"<string>",
"LastUpdated":"<mm/dd/yyyy hh:mm:ss>",
"SafeDisplayName":"<string>",
"SafeMetaData":[
{

"Key":"ServiceName",
"Value":"<string>"
}
],
"SafeName":"<string>",
"SafePermissions":"<list>",
"SafeSizeInBytes":"<long>"
},
…
]
Note:
The time returned in
LastUpdated is in UTC format.
Get Safe Details

This method returns information about a specific Safe in the Vault. It is demonstrated in the
sample code.
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Safes/{SafeName}

Parameter SafeName
Type String
Description The name of the Safe about which information is returned.
HTTP method GET
Header parameter

54 Safes
Type String
Body parameters
None
Result
{
"GetSafeResult": {
"ManagingCPM":"<CPM user>",
"NumberOfDaysRetention":<1-3650>,
"NumberOfVersionsRetention":<1-999>,
"OLACEnabled":<true/false>,
"SafeName":"<string>"
}
}

Add Safe
This method adds a new Safe to the Vault.
■ Add Safes
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Safes
HTTP method POST
Header parameter
Type String
Body parameters
{
"safe":{
"SafeName":"<Safe name>",
"Description":"<Description>",
"NumberOfDaysRetention":<1-3650>
}
}
Parameter SafeName (mandatory)
Type String

56 Safes
Description Name of a Safe to create.

Specify
n up to 28 characters.
The
n following characters aren’t allowed: \/:*<>".|
Do
n not start a Safe name with a space.
Valid values New Safe name
Parameter Description
Type String
Description Description of the new Safe.
Valid values Up to 100 characters.
Parameter OLACEnabled
Type Boolean
Description Whether or not to enable Object Level Access Control for the new Safe.
Parameter ManagingCPM
Type String
Description The name of the CPM user who will manage the new Safe.
Valid values An existing CPM user or "" to prevent the CPM from managing the Safe.
Parameter NumberOf VersionsRetention
Type Numeric
Description The number of retained versions of every password that is stored in the
Safe.
Specify either this parameter or NumberOfDaysRetention.
If you specify this parameter the NumberOfDaysRetention parameter is
disabled.
Valid values 1-999
Parameter NumberOf DaysRetention
Type Numeric
Description The number of days for which password versions are saved in the Safe.
Specify either this parameter or NumberOfVersionsRetention If you specify
this parameter the NumberOfVersionsRetention parameter is disabled.
Valid values 1-3650
Result
{
"safe":{

"SafeName":"<The name of the new Safe>",

"Description":"<Description for the new Safe>",
"ManagingCPM":"<Name of CPM user managing the Safe>",
}
}
Return Codes
Status code 201
Description Safe was added successfully
Update Safe
This method updates a single Safe in the Vault. The user who runs this web service requires the
following permissions:
In the Vault:
■ Manage Safes
In the Safe:
■ View Safe Members
URL
Note:

Parameter SafeName
Type String
Description The name of the Safe to update.
Valid values Safe name
HTTP method PUT

58 Safes
Header parameter
Type String
Body parameters
{
"safe":{
"SafeName":"<The name of the Safe>",
"Description":"<Description of the Safe>",
"ManagingCPM":”<Name of CPM user managing the Safe>”,
}
}
Parameter SafeName
Type String
Description The new name of the Safe, if you want to change it.
Specify
n up to 28 characters.
The
n following characters aren’t allowed: \/:*<>".|
Do
n not start a Safe name with a space.
Valid values Safe name.
Type String
Description The updated description of the Safe.
Valid values Up to100 characters
Parameter OLACEnabled
Type Boolean
Description Whether or not to enable Object Level Access Control.
Parameter ManagingCPM
Type String

Description Name of the CPM user who will manage the Safe.
Valid values An existing CPM user or "" to prevent the CPM from managing the Safe.
Parameter NumberOf VersionsRetention
Type Numeric
Description The number of versions of every password that is stored in the Safe.
Specify either this parameter or NumberOfDaysRetention.
If you specify this parameter, the NumberOfDaysRetention parameter is
disabled.
Valid values 1-999
Parameter NumberOf DaysRetention
Type Numeric
Description The number of days that versions are stored in the Safe.
Specify either this parameter or NumberOfVersionsRetention. If you
specify this parameter, the NumberOfVersionsRetention parameter is
disabled.
Valid values 1-3650
Result
{
"Safe":{
"SafeName":"<The name of the Safe>",
"Description":"<Description for the Safe>",
"ManagingCPM":"<Name of CPM user managing the Safe>",
}
}
Return Codes
Status code 200
Delete Safe
This method deletes a Safe from the Vault.
■ Manage Safe

60 Safes
URL
Note:

Parameter SafeName
Type String
Description The name of Safe to delete.
HTTP method DELETE
Header parameter
Type String
Body parameters
None
Result
{
}
Return Codes
Status code 204
Description No content

Search for a Safe

This method returns information about the Safes in the Vault that meet the criteria
specified in the search query. It is demonstrated in the sample code.
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Safes?query=
{Query}

Parameter Query
Type String
Description The search query.
HTTP method GET
Header parameter
Type String
Body parameters
None
Result
{
"SearchSafesResult":[ :{
"SafeName":"<Safe name>",
"Description":"<Description>",

62 Safes
},
},
…
]
}
Get Safe Account Groups

This method returns all the existing account groups in a specific Safe. The user
performing this task must have the following permissions in the Safe:
■ Add accounts
■ Update account content
■ Update account properties
■ Create folders
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/API/Safes/{SafeName}/AccountGroups

Parameter SafeName
Type String
Description The name of the Safe where the account groups are.
HTTP method GET
Header parameter
Type String

Body parameters
None
Result
{
"GroupID":<The group ID>,
"GroupName":<The group name>,
"GroupPlatformID":<The group platform ID>,
"Safe":<The group Safe name>
}
Parameter GroupID
Type String
Description The ID of the account group.
Parameter GroupName
Type String
Description The name of the account group.
Parameter GroupPlatformID
Type String
Description The ID of the platform associated with the account group.
Parameter Safe
Type String
Return Codes
Status code
Description

64 Safe Members
Safe Members
List Safe Members

This method returns a list of the members of the Safe. The user performing this task must have
the following permissions in the Safe:
■ ViewSafeMembers
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Safes/
{SafeName}/Members

Parameter SafeName
Type String
Description The name of the Safe whose Safe members will be listed.
HTTP method GET
Header parameter
Type String
Body parameters
None

Result
{
"UserName":"<String>",
"Permissions":
{
…
}
"UserName":"<String>",
"Permissions":
{
…
}
}
Add Safe Member

This method adds an existing user as a Safe member.
■ Manage Safe Members
URL
Note:
{SafeName}/Members

Parameter SafeName
Type String
Description The name of the Safe to add a member to.
HTTP method POST

66 Safe Members
Header parameter
Type String
Body parameters
{
"member":{
"MemberName":"<The name of the user to add as a Safe member>",
"SearchIn":"<Search for the member in the Vault or Domain>",
"MembershipExpirationDate":"<MM\DD\YY or empty if there is no
expiration date>",
"Permissions":<User’s permissions in the Safe>
[
{"Key":"UseAccounts", "Value":<true/false>},
{"Key":"RetrieveAccounts", "Value":<true/false>},
{"Key":"ListAccounts", "Value":<true/false>},
{"Key":"AddAccounts", "Value":<true/false>},
{"Key":"UpdateAccountContent", "Value":<true/false>},
{"Key":"UpdateAccountProperties", "Value":<true/false>},
{"Key":"InitiateCPMAccountManagementOperations",
"Value":<true/false>},
{"Key":"SpecifyNextAccountContent", "Value":<true/false>},
{"Key":"RenameAccounts", "Value":<true/false>},
{"Key":"DeleteAccounts", "Value":<true/false>},
{"Key":"UnlockAccounts", "Value":<true/false>},
{"Key":"ManageSafe", "Value":<true/false>},
{"Key":"ManageSafeMembers", "Value":<true/false>},
{"Key":"BackupSafe", "Value":<true/false>},
{"Key":"ViewAuditLog", "Value":<true/false>},
{"Key":"ViewSafeMembers", "Value":<true/false>},
{"Key":"RequestsAuthorizationLevel", "Value":<0/1/2>},
{"Key":"AccessWithoutConfirmation", "Value":<true/false>},
{"Key":"CreateFolders", "Value":<true/false>},
{"Key":"DeleteFolders", "Value":<true/false>},
{"Key":"MoveAccountsAndFolders", "Value":<true/false>}
]
}
Parameter MemberName (mandatory)
Type String
Description Vault or Domain user or group to add as a Safe member.

Note:
The MemberName must not contain '&' (ampersand).
Valid values Vault or domain user
Parameter SearchIn
Type String
Description The Vault or Domain to search for the user or group to add as a Safe
member.
Valid values Vault or the domains that are defined in the Vault
Default Vault
Parameter MembershipExpirationDate
Type String
Description Defines when the member’s Safe membership expires.

Specify "" for no expiration date.
Valid values Date format MM/DD/YY
Default no expiration
Parameter Permissions
Type Key/Value list
Description Safe member’s permissions in the Safe.
Valid values Permissions specified in the following table
Permissions
Parameter UseAccounts
Type Boolean
Description Use accounts but not view passwords.
Parameter RetrieveAccounts
Type Boolean
Description Retrieve and view accounts in the Safe.
Parameter ListAccounts
Type Boolean
Description View accounts list.

68 Safe Members
Parameter AddAccounts
Type Boolean
Description Add accounts in the Safe. Users who are given AddAccounts authorization
receive UpdateAccountProperties
as well. Users who have this permission automatically
have UpdateAccountProperties as well.
Parameter UpdateAccountContent
Type Boolean
Description Update existing account content.
Parameter UpdateAccountProperties
Type Boolean
Description Update existing account properties.
Parameter InitiateCPMAccountManagementOperations
Type Boolean
Description Initiate password management operations through CPM, such as changing

passwords, verifying and reconciling passwords. When this parameter is
set to false, the SpecifyNextAccountContent is automatically set to false.
Parameter SpecifyNextAccountContent
Type Boolean
Description Specify the password that will be used when the CPM changes the
password value. This parameter can only be specified when
InitiateCPMAccountManagementOperations is set to true.
When InitiateCPMAccountManagementOperations
is set to false this parameter is automatically set to false.
Parameter RenameAccounts
Type Boolean
Description Rename existing accounts in the Safe.
Parameter DeleteAccounts
Type Boolean
Description Delete existing passwords in the Safe.

Parameter UnlockAccounts
Type Boolean
Description Unlock accounts that are locked by other users.
Parameter ManageSafe
Type Boolean
Description Perform administrative tasks

in the Safe, including:
■ Update Safe properties
■ Recover the Safe
■ Delete the Safe
Parameter ManageSafe Members
Type Boolean
Description Add and remove Safe members, and update their authorizations in the
Safe.
Parameter BackupSafe
Type Boolean
Description Create a backup of a Safe and its contents, and store in another location.
Parameter ViewAuditLog
Type Boolean
Description View account and user activity in the Safe.
Parameter ViewSafeMembers
Type Boolean
Description View Safe members` permissions.
Parameter RequestsAuthorizationLevel
Type Numeric
Description Requests Authorization Level.

■ 0 – cannot authorize
■ 1 – authorization level 1

70 Safe Members
Valid values 0/1/2
Parameter AccessWithoutConfirmation
Type Boolean
Description Access the Safe without confirmation from authorized users. This
overrides the Safe properties that specify that Safe members require
confirmation to access the Safe.
Parameter CreateFolders
Type Boolean
Description Create folders in the Safe.
Parameter DeleteFolders
Type Boolean
Description Delete folders from the Safe.
Parameter MoveAccountsAndFolders
Type Boolean
Description Move accounts and folders in the Safe to different folders and subfolders.
Result
{
"member":{
"MemberName":"<The name of the Safe member who has just been
added>",
"SearchIn":"<The Vault or Domain where the user or group was found>",
"MembershipExpirationDate":"<MM\DD\YY> or empty if there is no
expiration date"
"Permissions":
{
"UseAccounts":<true/false>
"RetrieveAccounts":<true/false>
"ListAccounts":<true/false>
"AddAccounts":<true/false>
"UpdateAccountContent":<true/false>
"UpdateAccountProperties":<true/false>
"InitiateCPMAccountManagementOperations":<true/false>

"SpecifyNextAccountContent":<true/false>
"RenameAccounts":<true/false>
"DeleteAccounts":<true/false>
"UnlockAccounts":<true/false>
"ManageSafe":<true/false>
"ManageSafeMembers":<true/false>
"BackupSafe":<true/false>
"ViewAuditLog":<true/false>
"ViewSafeMembers":<true/false>
"RequestsAuthorizationLevel":<0/1/2>
"AccessWithoutConfirmation":<true/false>
"CreateFolders":<true/false>
"DeleteFolders":<true/false>
"MoveAccountsAndFolders":<true/false>
}
}
}
Return Codes
Status code 201

72 Safe Members
Update Safe Member

This method updates an existing Safe member.
The user who runs this web service requires the following permission
in the Vault:
URL
Note:
{SafeName}/Members/{MemberName}

Parameter SafeName
Type String
Description Name of the Safe to which the Safe member belongs.
Parameter MemberName
Type String
Description Vault/Domain user/group member to update.
HTTP method PUT
Header parameter
Type String

Body parameters
{
"member":{
"MembershipExpirationDate":"<MM\DD\YY or empty for no expiration>",
"Permissions":<User’s permissions in the Safe>
[
{"Key":"UseAccounts", "Value":<true/false>},
{"Key":"RetrieveAccounts", "Value":<true/false>},
{"Key":"ListAccounts", "Value":<true/false>},
{"Key":"AddAccounts", "Value":<true/false>},
{"Key":"UpdateAccountContent", "Value":<true/false>},
{"Key":"UpdateAccountProperties", "Value":<true/false>},
{"Key":"InitiateCPMAccountManagementOperations", "Value":<true/false>},
{"Key":"SpecifyNextAccountContent", "Value":<true/false>},
{"Key":"RenameAccounts", "Value":<true/false>},
{"Key":"DeleteAccounts", "Value":<true/false>},
{"Key":"UnlockAccounts", "Value":<true/false>},
{"Key":"ManageSafe", "Value":<true/false>},
{"Key":"ManageSafeMembers", "Value":<true/false>},
{"Key":"BackupSafe", "Value":<true/false>},
{"Key":"ViewAuditLog", "Value":<true/false>},
{"Key":"ViewSafeMembers", "Value":<true/false>},
{"Key":"RequestsAuthorizationLevel", "Value":<0/1/2>},
{"Key":"AccessWithoutConfirmation", "Value":<true/false>},
{"Key":"CreateFolders", "Value":<true/false>},
{"Key":"DeleteFolders", "Value":<true/false>},
{"Key":"MoveAccountsAndFolders", "Value":<true/false>}
]
}
}
Parameter MembershipExpirationDate
Type String
Description Defines when the user`s Safe membership expires. Specify “” for no
expiration date.
Parameter Permissions
Type Boolean/Numeric
Description User permission in the Safe.
Valid values Permissions specified in the following table.
Permissions
Parameter UseAccounts

74 Safe Members
Type Boolean
Description Use accounts but not view passwords.
Parameter RetrieveAccounts
Type Boolean
Description Retrieve and view accounts in the Safe.
Parameter ListAccounts
Type Boolean
Description View accounts list.
Parameter AddAccounts
Type Boolean
Description Add accounts in the Safe. Users who are given AddAccounts authorization
receive UpdateAccountProperties
as well. Users who have this permission automatically
have UpdateAccountProperties as well.
Parameter UpdateAccountContent
Type Boolean
Description Update existing account content.
Parameter UpdateAccountProperties
Type Boolean
Description Update existing account properties.
Parameter InitiateCPMAccountManagementOperations
Type Boolean
Description Initiate password management operations through CPM, such as changing

passwords, verifying and reconciling passwords. When this parameter is
set to false, the SpecifyNextAccountContent is automatically set to false.
Parameter SpecifyNextAccountContent
Type Boolean
Description Specify the password that will be used when the CPM changes the

password value. This parameter can only be specified when

InitiateCPMAccountManagementOperations is set to true.
When InitiateCPMAccountManagementOperations
is set to false this parameter is automatically set to false.
Parameter RenameAccounts
Type Boolean
Description Rename existing accounts in the Safe.
Parameter DeleteAccounts
Type Boolean
Description Delete existing passwords in the Safe.
Parameter UnlockAccounts
Type Boolean
Description Unlock accounts that are locked by other users.
Parameter ManageSafe
Type Boolean
Description Perform administrative tasks

in the Safe, including:
■ Update Safe properties
■ Recover the Safe
■ Delete the Safe
Parameter ManageSafe Members
Type Boolean
Description Add and remove Safe members, and update their authorizations in the
Safe.
Parameter BackupSafe
Type Boolean
Description Create a backup of a Safe and its contents, and store in another location.
Parameter ViewAuditLog
Type Boolean

76 Safe Members
Description View account and user activity in the Safe.
Parameter ViewSafeMembers
Type Boolean
Description View Safe members` permissions.
Parameter RequestsAuthorizationLevel
Type Numeric
Description Requests Authorization Level.

■ 0 – cannot authorize
Valid values 0/1/2
Parameter AccessWithoutConfirmation
Type Boolean
Description Access the Safe without confirmation from authorized users. This
overrides the Safe properties that specify that Safe members require
confirmation to access the Safe.
Parameter CreateFolders
Type Boolean
Description Create folders in the Safe.
Parameter DeleteFolders
Type Boolean
Description Delete folders from the Safe.
Parameter MoveAccountsAndFolders
Type Boolean
Description Move accounts and folders in the Safe to different folders and subfolders.

Result
{
"member":{
"MemberName":"<The name of the Safe member >",
"MembershipExpirationDate":"<MM\DD\YY or empty for no expiration date>"
"Permissions":
{
"UseAccounts":<true/false>
"RetrieveAccounts":<true/false>
"ListAccounts":<true/false>
"AddAccounts":<true/false>
"UpdateAccountContent":<true/false>
"UpdateAccountProperties":<true/false>
"InitiateCPMAccountManagementOperations":<true/false>
"SpecifyNextAccountContent":<true/false>
"RenameAccounts":<true/false>
"DeleteAccounts":<true/false>
"UnlockAccounts":<true/false>
"ManageSafe":<true/false>
"ManageSafeMembers":<true/false>
"BackupSafe":<true/false>
"ViewAuditLog":<true/false>
"ViewSafeMembers":<true/false>
"RequestsAuthorizationLevel":<0/1/2>
"AccessWithoutConfirmation":<true/false>
"CreateFolders":<true/false>
"DeleteFolders":<true/false>
"MoveAccountsAndFolders":<true/false>
}
}
}
Return Codes
Status code 201

78 Safe Members
Delete Safe Member

This method removes a specific member from a Safe.
URL
Note:
{SafeName}/Members/{MemberName}

Parameter SafeName
Type String
Description The name of the Safe from which to delete the member.
Parameter Member Name
Type String
Description The name of the Safe member to delete from the Safe’s list of members.
Valid values Vault user or domain user
HTTP method DELETE
Header parameter
Type String

Body parameters
None
Result
{
}
Return Codes
Status code 200

80 Platforms
Platforms
Get Platform Details

This method retrieves details of a specified platform from the Vault.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/API/Platforms/{PlatformName}

Parameter PlatformName
Type String
Description The unique ID/Name of the platform.
HTTP method GET
Header parameter
Type String
Body parameters
None

Result
{
"PlatformID":<Platform ID>
"Properties":<list of key\value>
"Active":<is active>
}
Parameter PlatformID
Type String
Description The unique ID of the platform.
Parameter Properties
Type List
Description List of all the parameters with their values from the Policy INI file of specific
platform
Parameter Active
Type true/false
Description According to the Master Policy and relevant exception (if it exists).
Return Codes
Status code 200
Description The request succeeded.
Import Platform
This method enables administrators to import a new platform.
URL
Note:
https://<IIS_Server_Ip>/API/Platforms/Import
HTTP method POST

82 Platforms
Header parameter
Type String
Body parameters
{
"ImportFile": {zip file byte array}
}
Parameter ImportFile (mandatory)
Type byte array
Description The file that contains the platform.
Default -
Result
{
"PlatformID": "PlatformID"
}
Type String
Description The unique ID of the platform.
Return Codes
Status 201
code
Description The request was created
Status 400
code

Description Bad request

The request was not created successfully, due to an invalid file
Status 403
code
Description Forbidden
The user creating the request must have the correct permissions, and must
be in the Vault Admins group
Status 409
code
Description Conflict
Platform already exists
Status 500
code
Description Internal Server Error

General error

84 Accounts
Accounts
Add Account
This method adds a new privileged account or SSH key to the Vault.
Note:
You require an additional license to add SSH keys to the Vault. For more
information, contact your CyberArk representative.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Account
HTTP method POST
Header parameter
Type String
Body parameters
{
"account" : {
"safe":"<Safe name>",
"platformID":"<Existing Platform ID>",

"address":"<Target address >",

"accountName":"<Object name (leave empty to auto generate)>",
"password":"<Password>",
"username":"<Target username>",
"disableAutoMgmt":"<true to disable account management by the CPM,
false to permit automatic management>",
"disableAutoMgmtReason":"<The reason for disabling CPM
management>",
"groupName":"<Name of the group with which the account will be
associated>",
"groupPlatformID":"<Group platform to base created group ID on, if ID
doesn't exist>",
"properties":
[
{"Key":"Port", "Value":"<port>"},
{"Key":"ExtraPass1Name", "Value":"Logon account name"},
{"Key":"ExtraPass1Folder", "Value":"Full pathname"},
{"Key":"ExtraPass1Safe", "Value":"Safename"},
{"Key":"ExtraPass3Name", "Value":"Reconcile account name"},
{"Key":"ExtraPass3Folder", "Value":"Full pathname"},
{"Key":"ExtraPass3Safe", "Value":"Safename"},
{"Key":"ParamName", "Value":"Parameter value"}
]
}
}
Parameter safe (mandatory)
Type String
Description The Safe where the account will be created.
Parameter platformID (mandatory)
Type String
Description The platform assigned to this account.
Valid values Platform ID
Parameter address
Type String
Description The name or address of the machine where the account will be used.
Valid values Machine name or address
Parameter accountName
Type String
Description The name of the account.

86 Accounts
Valid values Account name
Parameter password (mandatory)
Type String
Description The password value.
Valid values Password
Parameter username
Type String
Description The 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 will be associated .
Parameter groupPlatformID
Type String
Description The ID of the platform that manages the account group.
Valid values Group platform ID
Parameter disableAutoMgmt
Type Boolean
Description Whether or not automatic management will be disabled for this account.
Default false
Parameter disableAutoMgmtReason
Type String
Description The reason why the account was disabled for auto-management.
This parameter is only relevant if disableAutoMgmt is set to "true".
Valid values -
Parameter dynamicProperties
Type List
Description List of name=value pairs

Bind this list together with square brackets [ ] as shown in the example
above.
Valid values -
Parameter ExtraPass1Name

Type String
Description The name of the logon account.

Logon account
Valid values -
Parameter ExtraPass1Folder
Type String
Description The folder where the logon account is stored.
Valid values Folder
Default "Root"
Parameter ExtraPass1Safe
Type String
Description The Safe where the logon account is stored.
Parameter ExtraPass3Name
Type String
Description The name of the reconcile account.
Valid values Reconcile account
Parameter ExtraPass3Folder
Type String
Description The folder where the reconcile account is stored.
Valid values Folder
Default "Root"
Parameter ExtraPass3Safe
Type String
Description The Safe where the reconcile account is stored.
Result
{
}
Return Codes
Status code 201

88 Accounts
Description Account was added successfully
Add Pending Account

This method enables an account or SSH key that is discovered by an external scanner to be
added as a pending account to the Accounts Feed. This facilitates the privileged account
workflow, during which users can identify privileged accounts and determine which are onboarded
to the Vault.
Note:
In order to add SSH keys to the Vault, you require an additional license. For
more information, contact your CyberArk representative.
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/PendingAccounts
HTTP method POST
Header parameter
Type String
Body parameters
{
"pendingAccount":{
"UserName":"<user name>",
"Address":"<address>",
"AccountDiscoveryDate":"<YYYY-MM-DDThh:mm:ssZ>",

"AccountEnabled":"<enabled/disabled>",
"AccountOSGroups":"<group name>",
"AccountType":"<domain/local>",
"Domain":"<domain name>",
"PasswordNeverExpires":"<true/false>",
"OSVersion":"<OS version>",
"OU":"<OU>",
"AccountCategory":"<Privileged/Non-privileged>",
"UserDisplayName":"<user display name>",
"AccountDescription":"<description>",
"GID":"<GID>",
"UID":"<UID>",
"OSType":"<Windows/Unix>",
"DiscoveryPlatformType":"<platform name>",
"MachineOSFamily":"<workstation/server>",
"LastLogonDate":"<YYYY-MM-DDThh:mm:ssZ>",
"LastPasswordSetDate":"<YYYY-MM-DDThh:mm:ssZ>",
"AccountExpirationDate":"<YYYY-MM-DDThh:mm:ssZ>",
"AccountCategoryCriteria":"<criteria>"
}
}
Type String
Description The name of the account user.
Valid values User name
Parameter Address (mandatory)
Type String
Description The name or address of the machine where the account is used.
Parameter AccountDiscoveryDate (mandatory)
Type String
Description The date when the account was discovered. This parameter uses the
following standard: YYYY-MM-DDThh:mm:ssZ
Valid values Date and time
Parameter OSType
Type String
Description The type of OS where the password was discovered.
Valid values Windows/Unix
Parameter AccountEnabled

90 Accounts
Type String
Description The state of the account, as defined in the discovery source.
Note:
Domain accounts are discovered in the Active Directory, and
local accounts are discovered on machines.
If this parameter is not set, it will automatically be set to N/A.
Valid values enabled/disabled
Parameter AccountOSGroups
Type String
Description The name of the group that the account belongs to (eg, Administrators,
Operators, etc.)
Parameter AccountType
Type String
Description The type of account.
Valid values domain/local
Parameter DiscoveryPlatformType
Type String
Description The platform where the discovered account is used.
Valid values Platform name
Parameter Domain
Type String
Description The domain that the account belongs to.

This parameter is only relevant for domain accounts.
Valid values Domain name
Parameter LastLogonDate
Type String
Description The date when this account was last used to logon, as defined in the
discovery source. This parameter uses the following standard: YYYY-MM-
DDThh:mm:ssZ
Parameter LastPasswordSet
Type String
Description The date when this password was last set, as defined in the discovery
source. This parameter uses the following standard: YYYY-MM-

DDThh:mm:ssZ
Parameter PasswordNeverExpires
Type String
Description Whether or not this password ever expires, as defined in the discovery
source.
Parameter OSVersion
Type String
Description The version of the OS where the account was discovered.
Valid values Operating System
Parameter OU
Type String
Description The OU where the account is defined.
Valid values OU
Parameter AccountCategory
Type String
Description Whether the discovered account is privileged or non-privileged.

Valid values Privileged/Non-privileged
Parameter AccountCategoryCriteria
Type String
Description Criteria that determines whether or not the discovered account is

privileged. For example, the user or group name, etc.
Valid values String. Separate multiple strings with ";".
Parameter UserDisplayName
Type String
Description The user's display name.
Valid values User name
Parameter AccountDescription
Type String
Description A description of the user, as defined in the discovery source. This will be
saved as an account after it is added to the pending accounts.
Valid values -

92 Accounts
Parameter AccountExpirationDate
Type String
Description The expiration date of the account, as defined in the discovery source. This
parameter uses the following standard: YYYY-MM-DDThh:mm:ssZ
Parameter UID
Type String
Description The unique user ID.

This parameter is only relevant for Unix accounts.
Valid values User ID
Parameter GID
Type String
Description The unique group ID.

This parameter is only relevant for Unix accounts.
Valid values Group ID
Parameter MachineOSFamily
Type String
Description The type of machine where the account was discovered.

Valid values Workstation/Server
Result
None
Return Codes
Status code 201
Description Added Successfully
Status code 409
Description Exists in pending account
Status code 409
Description Exists in Vault

Delete Account
This method deletes a specific account in the Vault.
■ Delete accounts
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Accounts/
{AccountID}

Parameter AccountID
Type Number
Description The unique ID of the account to delete. This is retrieved by the Get Account
Details web service.
Valid values Account ID
HTTP method DELETE
Header parameter
Type String
Body parameters
None

94 Accounts
Result
{
}
Return Codes
Status code 204
Get Account Value

This method enables users to retrieve the password of an existing account that is identified by its
Account ID.
■ This web service will not return SSH Keys. If the request was sent for an SSK key, the
following error will be returned: "Failed to get the credentials of <AccountID>. Reason: The
account is of type SSH Key."
■ This web service will not be able to retrieve the password if a reason is required (according to
its effective Master Policy), and an error will be returned.
Note:
The ability to retrieve credentials using this REST API is intended for human
use only and is not recommended for applications or automated processes,
where application-based authentication is required.
For application or automated processes use cases, please refer to Application
Identity Manager (AIM) documentation.
URL
Note:
{AccountID}/Credentials

Parameter AccountID
Type String
Description The ID of the Account whose password will be retrieved.

HTTP method GET
Header parameter
Type String
Body parameters
None
Result
[
{
"Credentials":"VALUE"
} ]
Get Password Value (from v10)

This method enables users to retrieve the password or SSH key of an existing account that is
identified by its Account ID. It enables users to specify a reason and ticket ID, if required.
Note:
The ability to retrieve credentials using this REST API is intended for human
use only and is not recommended for applications or automated processes,
where application-based authentication is required.
For application or automated processes use cases, please refer to Application
Identity Manager (AIM) documentation.
This method can be used from v10 and replaces the Get Account Value method.
URL
Note:

96 Accounts
https://<IIS_Server_Ip>/PasswordVault/api/Accounts/
{accountId}/Password/Retrieve

Parameter AccountID
Type String
Description The unique ID of the account.
HTTP method POST
Header parameter
Type String
Body parameters
{
reason:"<Reason>",
TicketingSystemName: "<Ticketing system>",
TicketId: "<Ticketid>",
Version: <version number>,
ActionType: "<action type - show\copy\connect>
isUse: <true\false>,
Machine: "<my remote machine address>"
}
Parameter Reason
Type String
Description The reason that is required to retrieve the password/SSH key.
Valid values -
Default -

Parameter TicketId
Type String
Description The ticket ID of the ticketing system.
Valid values -
Default -
Parameter TicketingSystem
Type String
Description The name of the Ticketing System.
Valid values -
Default -
Parameter IsUse
Type Boolean
Description Internal parameter (for PSMP only).
Default false
Parameter ActionType
Type String
Description The action this password will be used for.
Valid values show/copy/connect
Default -
Parameter Machine
Type String
Description The address of the remote machine to connect to.
Valid values -
Default -
Parameter Version
Type integer
Description The version number of the required password. If there are no previous
versions, the current password/key version is returned.
Valid values A positive number
Default -

98 Accounts
Result
"<myPassword>"
Return Codes
Status 400
code
Description PASWS088E Failed to get content. Reason: Missing mandatory parameter

- Reason.
Status 400
code
Description PASWS089E Failed to get content. Reason: Input parameter for

[TicketingSystem] value is invalid. <reason for wrong ticketing system>
Status 400
code
Description PASWS090E Failed to get content. Reason: Input parameter for [TicketID]
value is invalid. <reaon for ticket validation error>
Status 401
code
Description PASWS041E Failed to get content. Reason: You are not authorized to
perform this action.
Status 404
code
Description PASWS040E Failed to get content. Reason: Content of account was not
found.
Change Credentials
This method marks the account for an immediate password change by the CPM to a new random
password.
The user who runs this web service requires the following permission in the Safe where the
privileged account is stored:
■ Initiate CPM password management operations
URL
Note:

{AccountID}/ChangeCredentials

Parameter AccountID
Type Number
Description The unique account ID of the account to change. This is retrieved by the
Get Account Details web service.
HTTP method PUT
Header parameter
Type String
Body parameters
{
"ImmediateChangeByCPM":<Yes/No>,
"ChangeCredsForGroup":<Yes/No>,
}
Parameter ImmediateChangeByCPM
Type String
Description Whether or not the account will be immediately changed by the CPM.
Specify Yes to initiate a password change by the CPM.
Valid values Yes/No
Parameter ChangeCredsForGroup
Type String
Description Whether or not to change the password in all accounts that belong to the

100 Accounts
same group.
This parameter is only relevant for accounts that belong to an account
group.
If this parameter does not belong to a group then it will be ignored.
Valid values Yes/No
Default Yes
Result
{
}
Return codes
Status code 200
Change credentials immediately

This method marks an account for an immediate credentials change by the CPM to a
new random value.
The user who runs this web service requires the following permission in the Safe where
the privileged account is stored:
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/API/Accounts/<AccountID>/Change
The following mandatory values are required in the URL:

Parameter AccountID
Type String

HTTP method POST
Header parameter
Type String
Body parameters
{
"ChangeEntireGroup" : true
}
Type Boolean
Description Whether or not the CPM will change the credentials in all the accounts that
belong to the same group.
group, and if this parameter does not belong to a group, it will be ignored. If
this account is part of an account group and this value is not specified, the
default value will be applied.
Default true
Return codes
Status code 200
Description Action triggered successfully.
Status code 400
Description This account has been deleted.

The account is not managed by the CPM
Automatic management for this account was disabled by the user
You do not have permission to initiate password management operations
on this account.
This account is locked by {LockedByUserName}.

102 Accounts
The {PolicyName} policy does not allow manual password changes.

This account cannot be automatically managed, because it is assigned to
an Inactive platform.
A CPM change task is not currently allowed.
You do not have permission to initiate a CPM password change operation
with a manual password.
Setting the password for the next CPM change cycle is not supported for
accounts that belong to a rotational group.
You do not have permission to store the password. Make sure you have
store permissions on the {SafeName} Safe.
Status code 403
Description You do not have permission to initiate password management operations

on this account.
Status code 500
Description An unexpected server error has occurred.
Change Credentials and Set Next Password

This method enables users to set the account's credentials to use for the next CPM
change.
The user who runs this web service requires the following permissions in the Safe where
Initiate CPM password management operations
Specify next password value
URL
Note:
Ip>/passwordvault/api/Accounts/<AccountID>/SetNextPassword

Parameter AccountID
Type String

HTTP method POST
Header parameter
Type String
Body parameters
{
"ChangeImmediately" : true,
"NewCredentials": "<credentials>"
}
Parameter ChangeImmediately
Type String
Description Whether or not the password will be changed immediately in the Vault.
Valid values -
Default -
Parameter NewCredentials (mandatory)
Type String
Description The new account credentials that will be allocated to the account in the
Vault.
Note:
Digits are never placed as the first or last character of the password,
regardless of the password policy or specifications.
If the specified password contains leading and/or trailing white
spaces, they will automatically be removed.
Valid values -
Default -
Return Codes
Status 200

104 Accounts
code
Description OK
Status 400
code
Status 400
code
Description The account is not managed by the CPM
Status 400
code
Description Automatic management for this account was disabled by the user
Status 400
code
Description This account is locked by {LockedByUserName}.
Status 400
code
Description The {PolicyName} policy does not allow manual password changes.
Status 400
code
Description This account cannot be automatically managed, because it is assigned to

Status 400
code
Description A CPM change task is not currently allowed.
Status 400
code
Description Setting the password for the next CPM change cycle is not supported for
accounts that belong to a rotational group.
Status 403
code
Description You do not have permission to initiate password management operations on

this account.
Status 403
code
Description You do not have permission to initiate a CPM password change operation
with a manual password.
Status 404
code

Description Account [<AccountID>] was not found.
Status 500
code
Description Unexpected server error has occurred.

106 Accounts
Change Credentials in the Vault

This method enables users to set the account's credentials and change it in the Vault.
This will not affect the credentials on the target device.
The user who runs this web service requires the following permission in the Safe where
Update password value
URL
Note:
Ip>/passwordvault/api/Accounts/<AccountID>/Password/Update

Parameter AccountID
Type String
HTTP method POST
Header parameter
Type String
Body parameters
Type String

Description Whether or not to change the password in all accounts that belong to the
same group.
group. If this parameter does not belong to a group, it will be ignored.
Valid values -
Default -
Parameter AutoGenerate
Type String
Description Whether or not the password will be generated according to the password
policy rules. If the CPM is not configured to enforce a password policy rule,
this parameter is irrelevant.
If the NewCredentails parameter contains a value, this parameter will be
ignored.
Valid values -
Default -
Parameter NewCredentials (mandatory)
Type String
Description The new account credentials that will be allocated to the account in the
Vault.
Note:
Digits are never placed as the first or last character of the password,
regardless of the password policy or specifications.
If the specified password contains leading and/or trailing white
spaces, they will automatically be removed.
Valid values -
Default -
Return Codes
Status 200
code
Description OK
Status 400
code
Status 400
code
Description This account is locked by {LockedByUserName}.
Status 400

108 Accounts
code
Description The {PolicyName} policy does not allow manual password changes.
Status 403
code
Description You do not have permission to store the password. Make sure you have
store permissions on the {SafeName} Safe.
Status 404
code
Description Account [<AccountID>] was not found.
Status 500
code
Description Unexpected server error has occurred.
Verify credentials (up to v9.9.5)

This method marks an account for verification by the CPM, and can be used in versions up to
v9.9.5.
URL
Note:
{AccountID}/VerifyCredentials

Parameter AccountID
Type Number
Description The unique account ID of the account to change. This is retrieved by the
Get Account Details web service.
HTTP method POST

Header parameter
Type String
Body parameters
None
Result
{
}
Return Codes
Status code 201
Verify credentials (from v9.10)

This method marks an account for verification by the CPM, and can be used in versions from
v9.10.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/API/Accounts/<AccountID>/Verify

Parameter AccountID
Type String

110 Accounts
HTTP method POST
Header parameter
Type String
Body parameters
None
Return codes
Status code 200
Description OK
Status code 400

PASWS143E Password is locked by another user.
EPVPA021E Verify task is not allowed due to policy restrictions.
EPVPA018E Failed to mark Object <ObjectName> for task Verify because
the Central Policy Manager is currently managing it.
EPVPA024E Task Verify is not allowed since group <GroupName> is
locked.
EPVPA019E Failed to mark Object <ObjectName> for task Verify because
the password Change task failed.
The account is not managed by the CPM.
Automatic management for this account was disabled by the user.
Status code 403
Description PASWS048E You do not have permission to initiate password

management operations on this account.
Status code 404
Description PASWS135E Account [<AccountID>] was not found.
Status code 500

Description An unexpected error occurred.
Reconcile credentials
This method marks an account for automatic reconciliation by the CPM.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/API/Accounts/<AccountID>/Reconcile

Parameter Account ID
Type String
HTTP method POST
Header parameter
Type String
Body parameters
None

112 Accounts
Return codes
Status code 200
Description OK
Status code 400

EPVPA018E Failed to mark Object <ObjectName> for task Reconcile
because the Central Policy Manager is currently managing it.
EPVPA021E Reconcile task is not allowed due to policy restrictions.
EPVPA024E Task Reconcile is not allowed since group <GroupName> is
locked.
The account is not managed by the CPM.
Automatic management for this account was disabled by the user.
Status code 403
Description PASWS048E You do not have permission to initiate password

management operations on this account.
Status code 404
Description PASWS135E Account [<AccountID>] was not found.
Status code 500

Get Account Details

This method returns information about an account. If more than one account meets the search
criteria, only the first account will be returned, although the Count output parameter will display
the number of accounts that were found.
Only the following users can access this account:
■ Users who are members of the Safe where the account is stored.
■ Users who have access to this specific account. For more information about object
level access control, refer to Object Level Access Control in the Privileged Account
Security Implementation Guide.
The user who runs this web service requires the following permission in the Safe:
■ List accounts
Note:
This method does not display the actual password.
If ten or more accounts are found, the Count Output parameter will show 10.
URL
Note:
http://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Accounts
HTTP method GET
Header parameter
Type String
Query parameters
The following parameters can be specified in the URL to filter the result:
Parameter Keywords

114 Accounts
Type String
Description Specify a keyword to search for. If you specify multiple keywords, the
search will include all the keywords. Separate keywords with a space.
Valid values Multiple keywords. Maximum of 500 characters.
Parameter Safe
Type String
Description Specify the name of a Safe to search. The search will be carried out only in
the Safes in the Vault that you are authorized to access.
Valid values Maximum of 28 characters
Examples
The following example shows how to retrieve an account with address: 10.10.1.1, user: root,
Safe: called UNIXAccountsSafe.
Example:
/PasswordVault/WebServices/PIMServices.svc/Accounts?Keywords=10.10.1.1,root&Saf
e
=UNIXAccountsSafe
Body parameters
None
Result
Note:
Only the account properties that are currently defined will be returned.
{
"Count":<the number of accounts that were found>,
"accounts":[
{
"AccountID":"<ID of Account1>",
"Properties":
[
{"Key":"Safe", "Value":"<Account1’s safe name>"},
{"Key":"Folder", "Value":"<Account1’s folder name>"},
{"Key":"Name", "Value":"<The name of Account1>"},
{"Key":"UserName", "Value":"<The username of Account1>"},
{"Key":"Address", "Value":"<The address of Account1>"}

]
"Internal Properties":
[
{"Key":"CPMInternal", "Value":"<Account1’s CPM’s internal reason>"},
{"Key":"ResetImmediately", "Value":"<ChangeTask, VerifyTask or
ReconcileTask>"},
{"Key":"NoGenerate", "Value":"<…>"}
]
}
]
}
Parameter Count
Type Integer
Description The number of accounts that were found by the requested query.
Parameter AccountID
Type Integer
Description The account's unique ID.
Parameter Safe
Type String
Description The name of the Safe where the account is stored.
Parameter Folder
Type String
Description The name of the folder where the account is stored.
Parameter Name
Type String
Description The name of the account.
Parameter Additional account properties that are defined, including internal properties.
Return Codes
Status code 200

116 Accounts
Update Account Details

This method updates an existing account's details. In order to execute this web service, all the
account’s details must be entered in the web service request. If the existing accounts properties
are not sent as part of the request, the properties will be removed from the account. Any values
sent in the request that were changed 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, the 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
Note:
IP>/PasswordVault/WebServices/PIMServices.svc/Accounts/
{AccountID}

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

HTTP method PUT
Header parameter
Type String
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. For more information,
refer to Appendix A: Account Properties in the Privileged Account Security
Implementation Guide.
Valid values Device type
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. For more information, refer
to Appendix A: Account Properties in the Privileged Account Security

118 Accounts
Implementation Guide.
Valid values Platform ID
Parameter Address
Type String
Description The new name or address of the machine where the account will be used.
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
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:
Example:

{
"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:
Example:
{
"Accounts":
{
"Folder":"Root",
"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:
Example:
{
"Accounts":
{
"Folder":"Root",
"Address":"10.10.10.10",
"UserName":"Administrator",
"GroupName":"WindowsAccountGroup",

120 Accounts
"Properties":[{
"Key":"Department", "Value":"Finance"},
{"Key":"GeoLocation", "Value":"UK"}]
}
}
Body parameters
None
Result
{
}
Return Codes
Status code 200
Description Account was updated successfully

Check-in an exclusive account

This method checks an exclusive account into the Vault.
■ If the account is managed automatically by the CPM, after it is checked in, the
password is changed immediately.
■ If the account is managed manually, a notification is sent to a user who is authorized
to change the password. The account is checked in automatically after it has been
changed.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/API/Accounts/<AccountID>/CheckIn

Parameter AccountID
Type String
Description The unique ID of the account to check into the Vault.
HTTP method POST
Header parameter
Type String
Body parameters
None

122 Accounts
Return codes
Status code 200
Description OK
Status code 400
Description PASWS140E This password must be changed manually before it becomes

available for additional users. Please change the password in the device,
then change it in the Vault using the "Change" button
Status code 403
Description Account cannot be changed in this mode due to missing permissions of the
user.
Status code 404
Description PASWS135E Account <account> was not found.
Status code 500
List Activity by ID
This method returns the activities of a specific account that is identified by its account ID.
URL
Note:
{AccountID}/Activities

Parameter SafeName (mandatory)
Type String
Description The name of the Safe where the account is stored.
Parameter AccountID (mandatory)
Type String
Description The ID of the account whose activities will be retrieved.

HTTP method GET
Header parameter
Type String
Body parameters
None
Result
{
"AccountName":"<string>",
"Path":"<string>",
"ActivityCode":"<integer>",
"Activity":"<string>",
"Time":"<string>",
"ClientID":"<integer>",
"Reason":"<string>",
"MoreInfo":"<details>"
…
}
Parameter AccountName
Type String
Description The name of the account whose activities will be returned.
Parameter Path
Type String
Description The full path of the account .
Parameter ActivityCode
Type Integer
Description The code identification of the specific activity.
Parameter Activity

124 Accounts
Type String
Description The activity that was performed.
Parameter Time
Type DateTime
Description The date and time when the activity took place.
Parameter UserName
Type String
Description The user who performed the activity.
Parameter Client ID
Type Integer
Description The ID of the CyberArk client from which the user connected and performed
the activity.
Parameter Reason
Type String
Description The reason given by the user for the activity.
Parameter MoreInfo
Type String
Description More information about the activity.

Account Groups
Add Account Group

This method enables application managers to define a new account group automatically, and
manage accounts as part of a group.
To create an account group, users require the following permissions in the Safe where the group
is created:
■ Add accounts
■ Create folders
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/AccountGroups/
HTTP method POST
Header parameter
Type String
Body parameters
{
"GroupName": "<Group name>",

126 Account Groups
"GroupPlatformID": "<Platform ID>",

"Safe": "<Safe name>"
}
Parameter GroupName (mandatory)
Type String
Description The name of the newly created group.
Parameter GroupPlatform (mandatory)
Type String
Description The name of the platform of the group.

The associated platform must be set to PolicyType=Group.
Parameter Safe (mandatory)
Type String
Description The name of the Safe where the group will be created.
Result
{
}
Parameter GroupID
Type String
Description The ID of the newly created group.
Parameter GroupName
Type String
Description The name of the newly created group.
Type String
Description The ID of the platform associated with the group.
Parameter Safe
Type String
Description The name of the Safe where the group exists.

Add Account to Account Group

This method adds an account as a member to an existing account group. The account can
contain either a password or an SSH key. All members of an account group must be stored in the
same Safe as the group itself.
To add an account as a member to an account group, users require the following permissions in
the Safe where the group is created:
■ Add accounts
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/AccountGroups/{GroupID}/Members

Parameter GroupID
Type String
Description The unique ID of account group.
Valid values Group ID
HTTP method POST
Header parameter
Type String

128 Account Groups
Body parameters
{
"AccountID": "<account ID>"
}
Parameter AccountID (mandatory)
Type String
Description The ID of the account that will be added as a member to the group.
Result
{
}
Get Account Group by Safe

This method returns all the account groups in a specific Safe. The user performing this
task must have the following permissions in the Safe:
■ Add accounts
■ Create folders
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/API/AccountGroups?Safe=<SafeName>

Parameter Safe
Type String
HTTP method GET

Header parameter
Type String
Body parameters
None
Result
{
"GroupID":<The group ID>,
"GroupName":<The group name>,
"GroupPlatformID":<The group platform ID>,
"Safe":<The group Safe name>
}
Parameter GroupID
Type String
Description The ID of the account group.
Parameter GroupName
Type String
Description The name of the account group.
Type String
Description The ID of the platform associated with the account group.
Parameter Safe
Type String
Return codes
Status code
Description

130 Account Groups
Get Account Group Members

This method returns all the members of an existing account group. These accounts can
be either password accounts or SSH Key accounts.
Note:
All members of account groups must be stored in the same Safe as the group itself.
The user performing this task must have the following permissions in the Safe:
■ Add accounts
■ Create folders
URL
Note:
Ip>/PasswordVault/API/AccountGroups/<GroupID>/Members

Parameter GroupID
Type String
Description The unique ID of the group
HTTP method GET
Header parameter
Type String

Body parameters
None
Result
[
{
"AccountID": "<ID of Account1>",
"SafeName": "<Account’s safe name>",
"PlatformID": "<Account’s Platform ID>",
"Address": "<The address of the account>",
"UserName": "<The username of the account>",
},
...
]
Parameter AccountID
Type String
Description The ID of the account that is a member of the group.
Parameter Safe
Type String
Description The name of the Safe where the privileged account is stored.
Type String
Description The name of the platform that is associated to this account.
Parameter Address
Type String
Description The address of the account.
Parameter Username
Type String
Description The username specified in the account.
Return codes
Status code
Description

132 Account Groups
Delete Member from Account Group

This method removes an account member from an account group. This account can be
either a password account or an SSH Key account.
The user performing this task must have the following permissions in the Safe:
■ Add accounts
■ Create folders
URL
Note:
Ip>/PasswordVault/API/AccountGroups/<GroupID>/Members/<AccountID>

Parameter GroupID
Type String
Description The unique ID of the group
Parameter AccountID
Type String
Description The unique ID of the account
HTTP method DELETE
Header parameter
Type String

Body parameters
None
Result
None
Return codes
Status code 204
Description Deleted

134 Policy/ACL
Policy/ACL
List Policy/ACL
This method gets a list of the privileged commands (OPM rules) associated with this
policy.
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Policy/
{PolicyId}/PrivilegedCommands

Parameter PolicyID
Type String
Description The ID of the policy for which the privileged commands will be listed.
HTTP method GET
Header parameter
Type String
Body parameters

Parameter PolicyId
Type text
Description The Policy Id provided in the URL.
Valid values Not empty
Result
{
"ListPolicyPrivilegedCommandsResult":
[
{"Command":"<command>",
"CommandGroup":"<true/false>",
"Id":"<number>",
"Type":"<Policy/Account>",
"IsGroup":"<true/false>",
"PermissionType":"<Allow/Deny>",
"PolicyId":"<policyID>",
"Restrictions":"<restrictions string, delimited by ;>",
"UserName":"<userName>"},
{…},
{…}
]
}
Return Codes
Status code 200
Description OK
Add Policy/ACL
This method adds a new privileged command rule to the policy.
URL
Note:
{PolicyId}/PrivilegedCommands

136 Policy/ACL

Parameter PolicyID
Type String
Description The ID of the policy to which the new privileged command rule will be
added.
HTTP method PUT
Header parameter
Type String
Body parameters
{
"Command":"<Command>",
"CommandGroup":<true/false>,
"Restrictions":"<Restrictions>",
"UserName":"<UserName>"
}
Parameter Command
Type text
Description The command to run.
Parameter CommandGroup
Type bool
Description Whether or not this is a command group.
Valid values True/False
Parameter PermissionType
Type text

Description Allow or Deny command.
Valid values Allow/Deny
Parameter PolicyId
Type text
Description The Policy Id, provided in the URL.
Parameter Restrictions
Type text
Description A restrictions string.
Valid values <restrictionName>=<Value>;<… or empty
Parameter UserName
Type text
Description The user this rule applies to.
Valid values User name, or "*" for all users
Result
{
"AddPolicyPrivilegedCommandResult":
{
"Command":"<command>",
"Id":"<number>",
"Restrictions":"<restrictions string, delimited by ;>",
"UserName":"<userName>"}
}
Return Codes
Status code 201
Description Policy ACL was added successfully

138 Policy/ACL
Delete Policy/ACL
This method deletes all privileged commands rules associated with the policy.
URL
Note:
{PolicyId}/PrivilegedCommands/{Id}

Parameter PolicyID
Type String
Description The ID of the policy from which the privileged commands will be deleted.
Parameter Id
Type String
Description The ID of the command rule that will be deleted.
HTTP method DELETE
Header parameter
Type String
Body parameters

Parameter PolicyId
Type text
Description The Policy Id provided in the URL.
Parameter Id
Type number
Description The Rule Id provided in the URL.
Result
None
Return Codes
Status code 204 (empty content)
Description Policy ACL with Id <Id> was deleted successfully.

140 Account/ACL
Account/ACL
List Account/ACL
This method gets a list of the privileged commands (OPM rules) associated with this account.
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Account/
{AccountAddress}|{AccountUserName}|
{AccountPolicyId}/PrivilegedCommands

Parameter AccountAddress
Type String
Description The address of the account whose privileged commands will be listed.
Parameter AccountUserName
Type String
Description The name of the account’s user.
Parameter AccountPolicyId
Type String
Description The Policy ID associated with this account.
HTTP method GET
Header parameter

Type String
Body parameters
None
Result
{
"ListAccountPrivilegedCommandsResult":
[
{"Command":"<command>",
"Id":"<number>",
"Restrictions":"<restrictions string, delimeted by ;>",
"UserName":"<userName>"},
{…},
{…}
]
}
Return Codes
Status code 200
Description OK

142 Account/ACL
Add Account/ACL
This method adds a new privileged command rule to the account.
URL
Note:
{AccountPolicyId}/PrivilegedCommands

Type String
Description The address of the account to which a new privileged command will be
added.
Type String
Type String
HTTP method PUT
Header parameter
Type String

Body parameters
{
"Command":"<Command>",
"CommandGroup":<true/false>,
"Restrictions":"<Restrictions>",
"UserName":"<UserName>"
}
Type text
Description The Policy Id of the account, provided in the URL.
Valid values -
Type text
Description The Address of the account, provided in the URL.
Type text
Description The User Name of the account, provided in the URL.
Parameter Command
Type text
Description The command to run.
Parameter CommandGroup
Type bool
Description Whether or not this is a command group.
Valid values True/False
Parameter PermissionType
Type text
Description Allow or Deny command.
Valid values Allow/Deny

144 Account/ACL
Parameter Restrictions
Type text
Description A restrictions string.
Valid values <restrictionName>=<Value>;<… or empty
Parameter UserName
Type text
Description The user this rule applies to.
Valid values User name, or "*" for all users
Result
{
"AddAccountPrivilegedCommandResult":
{
"Command":"<command>",
"Id":"<number>",
"Restrictions":"<restrictions string, delimeted by ;>",
"UserName":"<userName>"}
}
Return Codes
Status code 201
Description Policy ACL added successfully.

Delete Account ACL

This method deletes privileged commands rules associated with the account.
URL
Note:
{AccountPolicyId}/PrivilegedCommands/{id}

Type String
Description The address of the account for which the privileged command will be
deleted.
Type String
Parameter AccountPolicyID
Type String
Parameter Id
Type String
Description The ID of the command rule that will be deleted.
HTTP method GET/POST/PUT/DELETE

146 Account/ACL
Header parameter
Type String
Body parameters
None
Result
{
}
Return Codes
Status code 204 (empty content)
Description Policy ACL with Id <Id> was deleted successfully.

Onboarding Rules
Add Automatic Onboarding Rule

This method adds a new onboarding rule that filters discovered privileged and non-
privileged accounts. When an account matches a rule, it will automatically be onboarded
to the Safe that is defined in the rule and the password will be reconciled. If a newly
discovered account does not match any rule, it will be added to the Pending Accounts list.
The user who runs this web service must belong to the following group:
Vault Admins
Note:
Before you run this API, do the following:
Create the Safe and the reconcile account according to the rule’s definition.
Associate the reconcile account with the platform that is defined in the rule.
Make sure that the user whose credentials will be used for this session is a member of
the Safe specified in the TargetSafeName parameter with the Add accounts
permission.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/AutomaticOnboardingRules
HTTP method POST
Header parameter
Type String

148 Onboarding Rules
Valid A session token that was returned from the “Logon” method, encoded in
values BASE 64.
Body parameters
{
"TargetPlatformId": "<platform ID>",
"TargetSafeName": "<Safe name>",
"IsAdminIDFilter": <False>,
"MachineTypeFilter": "<Server>",
"SystemTypeFilter": "<Windows>",
"UserNameFilter": "<filter>",
"UserNameMethod": "<Begins>",
"AddressFilter": "<filter>",
"AddressMethod": "<Equals>",
"AccountCategoryFilter": "<Any>",
"RuleName": "<rule name>",
"RuleDescription": "<description>"
}
Parameter TargetPlatformId (mandatory)
Type String
Description The ID of the platform that the onboarded account will be associated with.
Valid values Platform ID, up to 99 characters
Default -
Parameter TargetSafeName (mandatory)
Type String
Description The name of the Safe where the onboarded account will be stored.
Valid values Safe name, up to 28 characters
Default -
Parameter IsAdminIDFilter
Type Boolean
Description Whether or not only accounts with the following admin ID will be onboarded
automatically according to this rule.
Unix accounts whose UID is 0
Windows accounts whose SID ends with 500
If this value is set to false, the admin ID will not be considered and all
accounts matching the rule will be onboarded.

Default false
Parameter MachineTypeFilter
Type String
Description The Machine Type by which to filter.
Valid values Any/Workstation/Server
Default Any
Parameter SystemTypeFilter (mandatory)
Type String
Description The System Type by which to filter.
Valid values Windows/ Unix
Default -
Parameter UserNameFilter
Type String
Description The name of the user by which to filter.
Valid values User name, up to 512 characters.
Default -
Parameter UserNameMethod
Type String
Description The method to use when applying the username filter (Equals / Begins with
/ Ends with). This parameter is ignored if UserNameFilter is not specified.
Valid values Equals/Begins/Ends
Default Equals
Parameter AddressFilter
Type String
Description The IP address or DNS domain name of the machine by which to filter.
Valid values Address, up to 255 characters.
Default -
Parameter AddressMethod
Type String
Description The method to use when applying the address filter (Equals / Begins with /
Ends with). This parameter is ignored if AddressFilter is not specified.
Valid values Equals/Begins/Ends
Default Equals
Parameter AccountCategoryFilter

Type String
Description Filter for privileged or non-privileged accounts.
Valid values Any/Privileged/Non-privileged
Default Any
Parameter RuleName
Type String
Description Name of the rule.

If this parameter is empty, the rule name will be automatically generated by
the system.
Valid values A unique name of 255 characters
Default Auto-generated name
Parameter RuleDescription
Type String
Description A description of the rule.
Valid values Free text, up to 255 characters
Default -
Return Codes
Status code 201
Description The automatic onboarding rule was added successfully
Status code 400
Status code 409
Description Conflict (if a rule exists with identical filters or the same rule name)
Status code 500
Description An error occurred
Delete Automatic Onboarding Rule

This method deletes an automatic onboarding rule from the Vault.
Vault Admins

URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/AutomaticOnboardingRules/{id}

Parameter id
Type Number
Description The unique ID of the rule to delete
HTTP method DELETE
Header parameter
Type String
values BASE 64.
Body parameters
None
Return Codes
Status code 200
Description Deletion was successful
Status code 402
Description The rule id doesn't exist
Status code 500

Get Automatic Onboarding Rules

This method returns information about all the defined onboarding rules.
Vault Admins
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/AutomaticOnboardingRules/
{?name=<rulename1,rulename2,...>}
The following optional value can be specified in the URL:

Parameter ?name
Type String
Description A filter that specifies the rule name. Separate a list of names with commas.
If none of the specified rules exist, the API returns an empty list.
If a value for this parameter is not specified, the API returns all of the rules.
Valid values A list of rule names, separated by commas.

For example: ?name=rulename1,rulename2
HTTP method GET
Header parameter
Type String
values BASE 64.
Body parameters
None

Result
{
"AutomaticOnboardingRules": [
{
"RuleId": <ID>,
"RuleName": "<rule name>",
"TargetPlatformId": "<platform ID>",
"TargetDeviceType": "<device type>",
"TargetSafeName": "<Safe name>",
"IsAdminIDFilter": <filter>,
"MachineTypeFilter": "<filter>",
"SystemTypeFilter": "<filter>",
"UserNameFilter": "<filter>",
"CreationTime": <time>,
"RulePrecedence": <precedence>,
"UserNameMethod": "<Equals>",
"AddressFilter": "<filter>",
"AddressMethod": "<Equals>",
"AccountCategoryFilter": "<Any>",
"RuleDescription": "<description>",
"LastOnboardedTime": <time>
},
],
"Total": <number>
}
Parameter RuleId
Type Number
Description A numeric identifier for the rule, assigned by the system.
Parameter RuleName
Type String
Description Name of the rule. This is either auto-generated or specified by the user when
the rule is created.
Parameter TargetPlatformId
Type String
Description The ID of the platform that the onboarded account will be associated with.
Parameter TargetDeviceType
Type String
Description Device type of the Target Platform
Parameter TargetSafeName
Type String

Description The name of the Safe where the onboarded account will be stored.
Security requirement: If the user is not an owner of the Safe, a null string will
be returned.
Parameter IsAdminIDFilter
Type Boolean
Description Whether or not only accounts with the following admin ID will be onboarded
automatically according to this rule.
Unix accounts whose UID is 0
Windows accounts whose SID ends with 500
If this value is set to false, the admin ID will not be considered and all
accounts matching the rule will be onboarded.
Parameter MachineTypeFilter
Type String
Description The Machine Type by which to filter.
Parameter SystemTypeFilter
Type String
Description The System Type by which to filter.
Parameter UserNameFilter
Type The name of the user by which to filter.
Description String
Parameter CreationTime
Type Time
Description The date and time when the rule was created.
Parameter RulePrecedence
Type Number
Description The order in which the rules are run.

Rules are ordered based on creation time. The most recently created rule
will have a precedence of 1, the next most recently created rule will have a
precedence of 2, and so on.
During discovery, when a new account is discovered, it is first compared to
the rule with precedence 1 to check if the account matches the rule's filters.
If so, the account is onboarded according to the rule. If not, the account is
compared to the next rule by precedence, and so on.
Parameter UserNameMethod
Type String
Description The method to use when applying the username filter.

Parameter AddressFilter
Type String
Description The IP address or DNS domain name of the machine by which to filter.
Parameter AddressMethod
Type String
Description The method to use when applying the address filter.
Parameter AccountCategoryFilter
Type String
Description Filter for privileged or non-privileged accounts.
Parameter RuleDescription
Type String
Description A description of the rule.
Parameter LastOnboardedTime
Type Time
Description The last time that an account was successfully onboarded using this rule.
Return Codes
Status code 200
Description The rules were retrieved successfully
Status code 500

156 My Requests
My Requests
Create a Request
This method creates an access request for a specific account. This account may be either
a password account or an SSH Key account.
URL
Note:
https://<IIS server IP>/PasswordVault/api/MyRequests
HTTP method POST
Header parameter
Type String
Body parameters
{
:"accountId": "<Account id>",
"reason":"<Reason>",
"TicketingSystemName": "<Ticketing system>",
"TicketId": "<Ticketid>",
"ConnectionComponent":"<Connection compmonent id>",
"MultipleAccessRequired":<true\false>,
"FromDate":<0-max integer>,

"ToDate":<0-max integer>,
"AdditionalInfo":
{
"<Additional Info name>":"<Addition Info value>",
"<Additional Info name>":"<Addition Info value>"
},
"UseConnect":<true\false>,
"ConnectionParams":
{
"<Connection parameter name>":
{
"value":"<Connection parameter value>",
"ShouldSave<true\false>"
},
<Connection parameter name>:
{
"ShouldSave<true\false>"
}
}
}
Parameter AccountId (mandatory)
Type String
Description The ID of the account to access.
Parameter Reason
Type String
Description The reason why the account needs to be accessed.
Parameter TicketingSystemName
Type String
Description The name of the Ticketing System specified in the request.
Parameter TicketID
Type String
Description The ticket ID given by the ticketing system.
Parameter MultipleAccess
Type Boolean
Description Whether or not the request is for multiple access.
Parameter FromDate
Type Integer
Description If the request is for a timeframe, the time from when the user wants to

158 My Requests
access the account, in Unix time.
Parameter ToDate
Type Integer
Description If the request is for a timeframe, the time until when the user wants to
access the account, in Unix time.
Parameter AdditionalInfo
Type List (key:value)
Description Additional information included in the request. A list of values that are
predefined in configuration.
Parameter UseConnect
Type Boolean
Description Whether or not the request is for connection through the PSM.
Parameter ConnectionComponent
Type String
Description If the connection is through PSM, the name of the connection component to
connect with, as defined in the configuration.
Parameter ConnectionParams
Type List
Description A list of parameters required to perform the connection, as defined in each

connection component configuration. These parameters are listed in the
table below.
Connection Parameters
Parameter value
Type String
Description The content of the parameter
Valid values Text
Default -
Parameter ShouldSave
Type Boolean
Description Whether or not this value will be saved with the account for future attempts
to connect to the remote machine.
Default false

Result
{
"RequestID":"<ID>",
"SafeName":"<Safe>",
"RequestorUserName":"<username>",
"RequestorReason":"(Ticket ID=<ticketid>)(Ticketing System=<ticketing
system>) (Emergency=<true/false>)(RefNo=<number>)
(PSMRemoteMachine=<machine>) <reason>",
"UserReason":"<reason>",
"CreationDate":<time/date>,
"Operation": "<operation>",
"ExpirationDate":<time/date>,
"OperationType":<operation>,
"AccessType":"<type>",
"ConfirmationsLeft":<number>,
"AccessFrom":<time/date>,
"AccessTo":<time/date>,
"Status":<status>,
"StatusTitle":"<title>",
"InvalidRequestReason":<number>,
"CurrentConfirmationLevel":<number>,
"RequiredConfirmersCountLevel2":<number>,
"TicketingSystemProperties":{
"Name":"name",
"Number":"<number>",
"Status":"<number>"
},|
"AdditionalInfo":{},
"AccountDetails":{
"AccountID":"<id>",
"Properties":{
"Address":"<address>",
"Safe":"<safe>",
"Folder":"<folder>",
"Name":"<accountname>",
"PolicyID":"<policy>",
"PlatformName":"<platform>",
"DeviceType":"<device>",
"LastVerifiedDate":"<date/time>",
"LastModifiedDate":"<date/time>",
"LastModifiedBy":"<user>",
"LastUsedDate":"<date/time>",
"LastUsedBy":"<username>",
"Username":"<username>",
"LockedBy":"<username>",
"CPMDisabled":"<reason>",
"CPMStatus":"<status>",

160 My Requests
"ManagedByCPM":"<True/False>",
"DeletedBy":"<username>",
"DeletionDate":"<date/time>",
"ImmediateCPMTask":"<string>",
"LastCPMTask":"<string>",
"CreationDate":"<date/time>",
"IsSSHKey":"<true/false>",
"CreationMethod":"<string>",
"CPMErrorDetails":"<error>",
"RetriesCount":"<number>",
"LastFailDate":"<date/time>",
"LastTask":"<task>"
}
},
"Confirmers":[
{
"Type":<type>,
"ID":<id>,
"Name":"<name>",
"Action":<number>,
"Reason":"<reason>",
"ActionDate":<date/time>,
"AdditionalDetails":{},
"Members":null
}
]
}
Parameter RequestID
Type Text
Description The request's unique ID, composed of the SafeName and internal
RequestID.
Parameter SafeName
Type Text
Description The name of the Safe where the account being requested is stored .
Parameter RequestorUserName
Type Text
Description The requestor's user name.
Parameter RequestorReason
Type Text
Description The requestor's reason for accessing the account, and any additional
information.
Parameter Ticket ID

Type Text
Description The unique ID of the ticket.
Parameter Ticketing System
Type Text
Description The ticketing system that issued the ticket.
Parameter Emergency
Type Boolean
Description Whether or not this request is critical.
Parameter RefNo
Type Integer
Description The unique reference number of this request.
Parameter PSMRemoteMachine
Type Text
Description The address of the remote machine to access using the account in this
request.
Parameter UserReason
Type Text
Description The reason given by the user for accessing the account in this request.
Parameter CreationDate
Type Integer
Description The time when the request was created, in Unix time.
Parameter Operation
Type Text
Description The operation that will be performed with the account in this request.
Parameter ExpirationDate
Type Integer
Description The time when the request will expire, in Unix time.
Parameter OperationType
Type Integer
Description The operation that was requested:

1 – Open
2 – Get file
4 – GetPassword
7 – All
Parameter AccessType

162 My Requests
Type Text
Description Whether the request is for single or multiple access.
Parameter ConfirmationsLeft
Type Integer
Description The number of confirmers who still need to respond to the request.
Parameter AccessFrom
Type Integer
Description The time from when the account is needed, in Unix time.
Parameter AccessTo
Type Integer
Description The time until when the account is needed, in Unix time.
Parameter Status
Type Integer
Description The request status:

1 - Waiting
2 - Confirmed
7 - Invalid
Parameter StatusTitle
Type Text
Description A description of the request status.
Parameter InvalidRequestReason
Type Integer
Description If the request is invalid, this indicates what caused it to become invalid:
0 - None
1 - Expired
2 - Already been used
4 - Missing supervisors
8 - Confirmation setting have changed
16 - Object has been deleted
32 - Incompatible client version
64 - Access time expired
128 - Rejected
Parameter CurrentConfirmationLevel
Type Integer
Description The current confirmation level - either level 1 or level 2.
Parameter RequiredConfirmersCountLevel2
Type Integer

Description The number of confirmers left to respond at level 2.
TicketingSystemProperties
Parameter Name
Type Text
Description The name of the ticketing system.
Parameter Number
Type Integer
Description Ticket number
Parameter Status
Type Integer
Description Ticket status

■ Validated
■ Not validated
■ Validation is not needed
AdditionalInfo
AccountDetails
Parameter AccountID
Type Text
Description An internal account ID, composed of SafeID and ObjectID.
Properties
Parameter Address
Type Text
Description The address of the machine where the account is used (IP or machine
name).
Parameter Safe
Type Text
Description The Safe where the account is stored in the Vault.
Parameter Folder
Type Text
Description The folder where the account is stored in the Vault.
Parameter Name
Type Text
Description The unique name of the account in this request.
Parameter PolicyID

164 My Requests
Type Text
Description The policy ID associated to this account.
Parameter PlatformName
Type Text
Description The platform associated to this account.
Parameter DeviceType
Type Text
Description The device type associated to this account.
Parameter LastVerifiedDate
Type Date/time
Description The time when this account was last verified.
Parameter LastModifiedDate
Type Date/time
Description The time when this account was last modified.
Parameter LastModifiedBy
Type Text
Description The name of the user who last modified the account specified in this
request.
Parameter LastUsedDate
Type Date/time
Description The last time when the account specified in this request was used.
Parameter LastUsedBy
Type Text
Description The name of the last user who accessed the account specified in this
request.
Parameter Username
Type Text
Description The name of the last user who accessed the account specified in this
request.
Parameter LockedBy
Type Text
Description If the account specified in this request is locked, the name of the user
locking it.
Parameter CPMDisabled

Type Text
Description If the account specified in this request is disabled for automatic

management, the reason why.
Parameter CPMStatus
Type Text
Description The status of CPM management for the account specified in this request.
Parameter ManagedByCPM
Type Boolean
Description Whether or not the account specified in this request is managed by the
CPM.
Parameter DeletedBy
Type Text
Description The name of the user who deleted the account specified in this request.
Parameter DeletionDate
Type Date/time
Description The time when the account specified in this request was deleted.
Parameter ImmediateCPMTask
Type Text
Description If the account is flagged for an immediate CPM task, the task that will be
performed.
Parameter LastCPMTask
Type Text
Description The last CPM task that was performed on the account specified in the
request.
Type Integer
Parameter IsSSHKey
Type Boolean
Description Whether or not this account contains an SSH key.
Parameter CreationMethod
Type Text
Description How this account was created in the Vault.
Parameter CPMErrorDetails

166 My Requests
Type Text
Description Details of any CPM errors that were issued for this account.
Parameter RetriesCount
Type Integer
Description The number of times that this account tried to log on to a remote machine.
Parameter LastFailDate
Type Date/time
Description The last time this account failed to log on to a remote machine.
Parameter LastTask
Type Text
Description The last task that this account was used for.
Confirmers
Parameter Type
Type Integer
Description The type of confirmer:

1 - User
2 - Group
Parameter ID
Type Integer
Description Internal ID of the confirming user/group.
Parameter Name
Type Text
Description The name of the confirming user/group.
Parameter Action
Type Integer
Description The action performed by the confirmer:

0 – Reject
1 – Confirm
2 – None
Parameter Reason
Type Text
Description The reason specified by the confirmer for their action.
Parameter ActionDate
Type Integer
Description The time when the confirmer performed their action, in Unix time.

AdditionalDetails
Members
Get My Requests
This method returns a list of the end user's requests.
URL
Note:
https://<IIS_Server_Ip/PasswordVault/api/MyRequests?onlywaiting=
{bool}&expired={bool}

Parameter OnlyWaiting
Type Boolean
Description Only requests waiting for approval will be listed.
Default false
Parameter Expired
Type Boolean
Description Expired requests will be included in the list.
Default false
HTTP method GET
Header parameter
Type String

168 My Requests
Body parameters
None
Result
{
"Requests": [
{
"RequestID": "<Request ID, SafeName_RequestID>",
"SafeName": "<Safe name>",
"RequestorUserName": "<Requestor user name>",
"RequestorReason": "<Requestor reason>",
"UserReason": "<User reason>",
"CreationDate": <Request creation date (Unix time)>,
"Operation" : <request operation description>,
"ExpirationDate": <Request expiration date (Unix time)>,
"OperationType": <Which operation was requested>,
"AccessType": "< OneTime\Multiple Access>",
"ConfirmationsLeft": <How many confirmers are still needed>,
"AccessFrom": <When the access time frame starts(Unix time)>,
"AccessTo": <When the access time frame ends (Unix time)>,
"Status": <Request Status>,
"StatusTitle": <Request Status description>,
"InvalidRequestReason": <Why request become invalid>,
"CurrentConfirmationLevel": <The request confirmation level>,
"RequiredConfirmersCountLevel2": <Level 2 confirmers that are still needed>,
"TicketingSystemProperties": {
"Name": "<Ticketing system name>",
"Number": <Ticket number>
"Status": <1/2/3>
},
"AdditionalInfo": {
"Reference No": "<???>",
"Emergency": "<Is it an emergency request>"
},
"AccountDetails": {
"AccountID": "<Internal account ID>",
"Properties": {
"Name": "<Account name in the vault>",
"Folder": "<Folder>",
"Safe": "<Safe>",
"Address": "<Address, can be IP or machine name>",
"UserName": "<User name>",
"LastUsedDate": "<Account last used date >"
}
}
…
]
}

Parameter RequestID
Type Text
RequestID.
Parameter SafeName
Type Text
Type Text
Type Text
information.
Type Text
Description The reason why the user is requesting access to the account.
Type Integer
Parameter Operation
Type Text
Description Requestor's description of the operation to perform.
Type Integer
Type Integer

1 – Open
2 – Get file
4 – GetPassword
7 – All
Type Text

170 My Requests
Type Integer
Type Integer
Parameter AccessTo
Type Integer
Parameter Status
Type Integer

1 - Waiting
2 - Confirmed
7 - Invalid
Type Text
Type Integer
0 - None
1 - Expired
128 - Rejected
Type Integer
Type Integer

Parameter Name
Type Text
Parameter Number
Type Integer
Parameter Status
Type Integer

■ Validated
■ Not validated
AdditionalInfo
Parameter Reference No
Type Integer
Parameter Emergency
Type Boolean
AccountDetails
Parameter AccountID
Type Text
Properties
Parameter Name
Type Text
Description The name of the account in the Vault.
Parameter Folder
Type Text
Parameter Safe
Type Text

172 My Requests
Parameter Address
Type Text
name).
Parameter UserName
Type Text
Description The name of the user who will use the account.
Type Integer
Description The last time the account was used, in Unix time.

Delete My Request
This method deletes a request made by a user.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/myrequests/{RequestID}

Parameter RequestID
Type Text
RequestID.
HTTP method DELETE
Header parameter
Type String
Body parameters
None
Result
{
}

174 My Requests
Return Codes
Status code 204
Get Details of My Requests

This method returns details of all the requests in My Requests list.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/myrequests/{RequestID}

Parameter RequestID
Type Text
RequestID.
HTTP method GET
Header parameter
Type String
Body parameters
None

Result
{
"RequestorFullName": "<Requestor full name>",
"RequestID": "<request ID, SafeName_RequestID>",
"Number": <Ticket number>,
"Status": <1/2/3>
},
"AdditionalInfo": {
"Reference No": "<external reference number>",
" EmergencyIndication": "<Is it an emergency request>"
},
"AccountDetails": {
"AccountID": "<Full account id, SafeID_ObjectID>",
"Properties": {
"Name": "<Object name in the vault>",
"Folder": "<The object folder name in the vault >",
"Safe": "<The object safe name in the vault>",
"Address": "<The account address, IP or machine name>",
"UserName": "<The account name in the target machine>",
"LastUsedDate": "<Last used date of this account>"
}
},
"Confirmers": [
{
"Type": <User\Group>,
"ID": <Internal confirmer ID>,
"Name": "<Confirmer name>",
"Action": <Which action this user perform>,

176 My Requests
"Reason": "<Confirmer reason>",

"ActionDate": <Action date (Unix time)>,
"AdditionalDetails": {
"fullname": "<User full name>",
"email": "<User business email>",
"phone": "<User phone>"
},
…
],
"Members": [
{
"UserID": <Internal User ID>,
"UserName": "<Confirmer user name>",
}
},
…
]
}
Parameter RequestID
Type Text
RequestID.
Parameter SafeName
Type Text
Type Text
Type Text
information.
Type Integer

Type Integer
Type Integer

1 – Open
2 – Get file
4 – GetPassword
7 – All
Type Text
Type Integer
Type Integer
Parameter AccessTo
Type Integer
Parameter Status
Type Integer

1 - Waiting
2 - Confirmed
7 - Invalid
Type Text
Type Integer
0 - None
1 - Expired

178 My Requests

128 - Rejected
Type Integer
Type Integer
Parameter Name
Type Text
Parameter Number
Type Integer
Parameter Status
Type Integer

■ Validated
■ Not validated
AdditionalInfo
Type Integer
Parameter Emergency
Type Boolean
AccountDetails
Parameter AccountID
Type Text
Properties

Parameter Name
Type Text
Parameter Folder
Type Text
Parameter Safe
Type Text
Parameter Address
Type Text
name).
Parameter UserName
Type Text
Type Integer
Confirmers
Parameter Type
Type Integer

1 - User
2 - Group
Parameter ID
Type Integer
Parameter Name
Type Text
Parameter Action
Type Integer

0 – Reject

180 My Requests
1 – Confirm
2 – None
Parameter Reason
Type Text
Type Integer
AdditionalDetails
Parameter FullName
Type Text
Description The confirmer's full name.
Parameter Email
Type Text
Description The confirmer's businesss email.
Parameter Phone
Type Text
Description The confirmer's phone number.
Members
Parameter UserID
Type Integer
Description The confirmer's internal user ID.
Parameter UserName
Type Text
Description The confirmer's user name.
AdditionalDetails
Parameter FullName
Type Text
Parameter Email
Type Text
Parameter Phone

Type Text

182 Confirm Requests
Confirm Requests
Get Incoming Request List

This method returns a list of all the requests for the confirmer to respond to.
URL
Note:
Ip/PasswordVault/api/IncomingRequests?onlywaiting={bool}&expired=
{bool}

Parameter OnlyWaiting
Type Boolean
Description Only requests waiting for approval will be listed.
Default false
Parameter Expired
Type Boolean
Description Expired requests will be included in the list.
Default false
HTTP method GET

Header parameter
Type String
Body parameters
None
Result
{
"IncomingRequests": [
{
"RequestID": "<Request ID, SafeName_RequestID>",
"Number": <Ticket number>
"Status": <1/2/3>
},
"AdditionalInfo": {
"Reference No": "<???>",
"Emergency": "<Is it an emergency request>"
},
"AccountDetails": {
"AccountID": "<Internal account ID>",

"Properties": {
"Name": "<Account name in the vault>",
"Folder": "<Folder>",
"Safe": "<Safe>",
"Address": "<Address, can be IP or machine name>",
"UserName": "<User name>",
"LastUsedDate": "<Account last used date >"
}
}
…
]
Parameter RequestorFullName
Type Text
Description Requestor's full name
Parameter RequestID
Type Text
RequestID.
Parameter SafeName
Type Text
Type Text
Type Text
information.
Type Text
Description The reason why the user is requesting access to the account.
Type Integer
Parameter Operation
Type Text

Description Requestor's description of the operation to perform.
Type Integer
Type Integer

1 – Open
2 – Get file
4 – GetPassword
7 – All
Type Text
Type Integer
Type Integer
Parameter AccessTo
Type Integer
Parameter Status
Type Integer

1 - Waiting
2 - Confirmed
7 - Invalid
Type Text
Type Integer
0 - None

1 - Expired
128 - Rejected
Type Integer
Type Integer
Parameter Name
Type Text
Parameter Number
Type Integer
Parameter Status
Type Integer

■ Validated
■ Not validated
AdditionalInfo
Type Integer
Parameter Emergency
Type Boolean
AccountDetails
Parameter AccountID

Type Text
Properties
Parameter Name
Type Text
Parameter Folder
Type Text
Parameter Safe
Type Text
Parameter Address
Type Text
name).
Parameter UserName
Type Text
Type Integer

Get Details of a Request for Confirmation

This method returns details of a specific request in the Incoming Requests list.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/incomingrequests/{requestID}

Parameter RequestID
Type Text
RequestID.
HTTP method GET
Header parameter
Type String
Body parameters
None

Result
{
"RequestID": "<request ID, SafeName_RequestID>",
"Number": <Ticket number>,
"Status": <1/2/3>
},
"AdditionalInfo": {
"Reference No": "<external reference number>",
" EmergencyIndication": "<Is it an emergency request>"
},
"AccountDetails": {
"AccountID": "<Full account id, SafeID_ObjectID>",
"Properties": {
"Name": "<Object name in the vault>",
"Folder": "<The object folder name in the vault >",
"Safe": "<The object safe name in the vault>",
"Address": "<The account address, IP or machine name>",
"UserName": "<The account name in the target machine>",
"LastUsedDate": "<Last used date of this account>"
}
},
"Confirmers": [
{
"Type": <User\Group>,
"ID": <Internal confirmer ID>,
"Name": "<Confirmer name>",
"Action": <Which action this user perform>,

"Reason": "<Confirmer reason>",

"ActionDate": <Action date (Unix time)>,
},
…
],
"Members": [
{
"UserID": <Internal User ID>,
"UserName": "<Confirmer user name>",
}
},
…
]
}
Parameter RequestorFullName
Type Text
Description Requestor's full name
Parameter RequestID
Type Text
RequestID.
Parameter SafeName
Type Text
Type Text
Type Text
information.

Type Integer
Type Integer
Type Integer

1 – Open
2 – Get file
4 – GetPassword
7 – All
Type Text
Type Integer
Type Integer
Parameter AccessTo
Type Integer
Parameter Status
Type Integer

1 - Waiting
2 - Confirmed
7 - Invalid
Type Text
Type Integer

0 - None
1 - Expired
128 - Rejected
Type Integer
Type Integer
Parameter Name
Type Text
Parameter Number
Type Integer
Parameter Status
Type Integer

■ Validated
■ Not validated
AdditionalInfo
Type Integer
Parameter EmergencyIndication
Type Boolean
AccountDetails

Parameter AccountID
Type Text
Properties
Parameter Name
Type Text
Parameter Folder
Type Text
Parameter Safe
Type Text
Parameter Address
Type Text
name).
Parameter UserName
Type Text
Type Integer
Confirmers
Parameter Type
Type Integer

1 - User
2 - Group
Parameter ID
Type Integer
Parameter Name
Type Text

Parameter Action
Type Integer

0 – Reject
1 – Confirm
2 – None
Parameter Reason
Type Text
Type Integer
AdditionalDetails
Parameter FullName
Type Text
Parameter Email
Type Text
Parameter Phone
Type Text
Members
Parameter UserID
Type Integer
Description The confirmer's internal user ID.
Parameter UserName
Type Text
Description The confirmer's user name.
AdditionalDetails
Parameter FullName
Type Text

Parameter Email
Type Text
Parameter Phone
Type Text

Confirm Request
This method enables a request confirmer to confirm a single request, identified by its
request ID.
URL
Note:
https://<IIS server IP>/PasswordVault/api/incomingrequests/

{RequestID}/confirm

Parameter RequestID
Type Text
Description The unique ID of the request to confirm.
HTTP method POST
Header parameter
Type String
Body parameters
{
"Reason": "<Confirmer reason>"
}

Parameter Reason
Type Text
Description The confirmer's reason for confirming this request.
Result
{
}
Return Codes
Status code 200

Reject Request
This method enables a request confirmer to reject a single request, identified by its
request ID.
URL
Note:
https://<IIS server IP>/PasswordVault/api/incomingrequests/{RequestID}/reject

Parameter RequestID
Type Text
Description The unique ID of the request to reject.
HTTP method POST
Header parameter
Type String
Body parameters
{
"Reason": "<Confirmer reason>"
}
Parameter Reason
Type Text

Description The confirmer's reason for rejecting this request.
Result
{
}
Return Codes
Status code 200

200 Connections
Connections
Connect Through PSM

This method enables you to connect to an account through PSM (PSMConnect) using a
connection method defined in the PVWA.
A Response header defines which connection method is returned.
For more information, refer to Configuring the PSM Session User Experience for
Connections Through PVWA in the Privileged Account Security Implementation Guide.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/Accounts/{accountId}/PSMConnect

Parameter AccountID
Type String
Description The unique ID of the account to retrieve and use to connect to the target
system through PSM.
Resource information
HTTP method POST
Header parameter
Type String
Descriptio The token that identifies the session, encoded in BASE 64.
n
Parameter Accept
Type String

Descriptio PVWA
n Optional
configuratio Connection method
values
n
RDP application/json RDPFile (JSON)
application/octe RDPFile (octet-stream raw)

t-stream , */ *
PSMGW */* PSMGW (JSON)
Note:
Returns the
HTML5
connection
data.
PSMGW must
be configured
before using
this REST API
in order to
receive a
PSMGW resp
onse.
Body parameters
{
"reason":"<Reason>",
"TicketingSystemName":"<Ticketing system>",
"TicketId":"<Ticketid>",
"ConnectionComponent":"<Connection component id>",
"ConnectionParams": {
"<Connection parameter name>": {
"ShouldSave":<true\false>
},
"<Connection parameter name>": {
"ShouldSave":<true\false>
}
}
}
Parameter ConnectionComponent (mandatory)
Type String
Description The name of the connection component to connect with as defined in the
PVWA configuration
Parameter Reason

202 Connections
Type String
Description The reason that is required to request access to this account.
Parameter TicketingSystemName
Type String
Description The name of the Ticketing System used in the request.
Parameter TicketId
Type String
Description The ticket ID of the ticketing system.
Parameter ConnectionParams
Type List
Description A list of parameters required to perform the connection, as defined in each

connection component configuration. These parameters are listed in the
table below.
Example:
ConnectionParam:
{
LogonDomain:
{
value:"MyDomain",
ShouldSave:true
},
AllowMappingLocalDrives:
{
value: "Yes",
ShouldSave:false
}
}
Connection Parameters
Parameter value
Type String
Description The content of the parameter
Valid values Text
Default -
Parameter ShouldSave
Type Boolean
Description Whether or not this value will be saved with the account for future attempts
to connect to the remote machine.

Default false
Result
Response header
Parameter ConnectionMethod
Type Boolean
Description The method set in the ConnectionType parameter in the body parameters.
Values PSMGW
RDPFile
Response body
There are two possible responses, depending on the connection method.
R D P file
full address:s:<address>
server port:i:<port>
username:s:<username>
alternate shell:s:<username>
desktopwidth:i:<number>
desktopheight:i:<number>
screen mode id:i:<number>
redirectdrives:i:<number>
drivestoredirect:s:<string>
redirectsmartcards:i:<number>
EnableCredSspSupport:i:<number>
redirectcomports:i:<number>
remoteapplicationmode:i:<number>
use multimon:i:<number>
span monitors:i:<number>
P S MGW
{
"PSMGWURL": "<URL>",
"PSMGWRequest": "<Base64 Encoded Data>"
}
Parameter PSMGWURL
Type String
Description The full URL of the web server which serves the HTML5 service

204 Connections
Parameter PSMGWRequest
Type String
Description Base64 encoded data that is passed to the web server and is essential for
the actual web server HTML5 connection. This data is passed through the
web server HTTP Post request.
Following the PSMGW response, connect to PSMGW by creating a POST request to the

PSMGWURL based on the parameter received in the response. In the post request
body, send the PSMGWRequest parameter as JSON:
{
PSMGWRequest: <Base64Response>
}
Import Connection Component

This method enables administrators to import a new connection component.
URL
Note:
https://<IIS_Server_Ip>/API/ConnectionComponents/Import
HTTP method POST
Header parameter
Type String
Body parameters

{
"ImportFile": {zip file byte array}
}
Parameter ImportFile (mandatory)
Type byte array
Description The file that contains the connection component.
Default -
Result
{
"ConnectionComponentID": "ConnectionComponentID"
}
Parameter ConnectionComponentID
Type String
Description The unique ID of the connection component.
Return Codes
Status 201
code
Description The request was created
Status 400
code

The request was not created successfully, due to an invalid file
Status 403
code
The user creating the request must have the correct permissions, and must
be in the Vault Admins group
Status 409
code
Description Conflict
Connection component already exists
Status 500

206 Connections
code
Description Internal Server Error

General error

Applications
List Applications
This method returns a list of all the applications in the Vault.
■ Audit Users
URL
Note:
Ip>/PasswordVault/WebServices/PIMServices.svc/Applications/
Add the following query values in the URL:

Parameter AppID
Type String
Description Application name.
Parameter Location
Type String
Description Location of the application in the Vault hierarchy.
Valid values Location
Default \
Parameter IncludeSublocations
Type Boolean
Description Whether or not the search will be performed in sublocations of the specified
location.
Default true

208 Applications
Example:
/PasswordVault/WebServices/PIMServices.svc/Applications?Location=%5CApplications
&AppID=App-1
HTTP method GET
Header parameter
Type String
Body parameters
None
Result
{
"application": [
{
"AccessPermittedFrom":<string>,
"AccessPermittedTo":<string>,
"AllowExtendedAuthenticationRestrictions":<bool>,
"AppID":<string>,
"BusinessOwnerEmail":"<string>",
"BusinessOwnerFName":"<string>",
"BusinessOwnerLName":"<string>",
"BusinessOwnerPhone":"<string>",
"Disabled":<bool>,
"ExpirationDate":<string>,
}]
}
Return Codes
Status code 200

List a Specific Application

This method returns information about a specific application.
■ Audit Users
URL
Note:
You cannot search for an application whose name includes @. To find these
applications, list all applications, then find the specific application in the returned
applications list.
Ip>/PasswordVault/WebServices/PIMServices.svc/Applications/{AppID}

Parameter AppID
Type String
Description The name of the application about which information is returned.
HTTP method GET
Header parameter
Type String
Body parameters
None

210 Applications
Result
{
"application": [
{
"AccessPermittedFrom":<string>,
"AccessPermittedTo":<string>,
"AllowExtendedAuthenticationRestrictions":<bool>,
"AppID":"<string>",
"BusinessOwnerEmail":"<string>",
"BusinessOwnerFName":"<string>",
"BusinessOwnerLName":"<string>",
"BusinessOwnerPhone":"<string>",
"Disabled":<bool>,
"ExpirationDate":<mm/dd/yyyy>,
}
]
}
Return Codes
Status code 200

Add Application
This method adds a new application to the Vault.
The user who adds this application requires the following permission in the Vault:
■ Manage Users
URL
Note:
HTTP method POST
Header parameter
Type String
Body parameters
{
"application":{
"AppID":"<application Name>",
"Description":"<description of the application>",
"Location":”<existing location from the Vault>”,
"AccessPermittedFrom":<the hour that access is permitted to the application>,
"AccessPermittedTo":<the hour that access is permitted to the application>,
"ExpirationDate":<expiration date of the application>,
"Disabled":"<whether the application is disabled>",
"BusinessOwnerFName":"<business owner first name>",
"BusinessOwnerLName":"<business owner last name >",
"BusinessOwnerEmail":"<business owner email >",

212 Applications
"BusinessOwnerPhone":"<business owner phone>"

}
}
Parameter AppID (mandatory)
Type String
Description Application name.
Note:
Specify fewer than 128 characters.
Do not include ampersand (“&”).
Application names can include @, but a
search for applications cannot include
this character.
Type String
Description Description of the application.
Note:
Specify up to 29 characters.
Valid values -
Parameter Location
Type String
Description Location of the application in the Vault hierarchy.
Note:
To insert a backslash in the location
path, use a double backslash.
Valid values -
Parameter AccessPermittedFrom
Type Integer
Description The hour that access is permitted to the application
Valid values 0-23
Parameter AccessPermittedTo
Type Integer

Description The hour that access is permitted to the application
Valid values 0-23
Type String
Description The date when the application expires.
Valid values mm-dd-yyyy
Parameter Disabled
Type Boolean
Description Whether the application is disabled.
Default false
Parameter BusinessOwnerFName
Type String
Description The first name of the business owner.
Note:
Valid values
Parameter BusinessOwnerLName
Type String
Description The last name of the business owner.
Valid values -
Parameter BusinessOwnerEmail
Type String
Description The email of the business owner.
Valid values
Parameter BusinessOwnerPhone
Type String
Description The phone number of the business owner.
Note:
Valid values Business owner's phone number.

214 Applications
Result
{
}
Return Codes
Status code 201
Description Application added successfully.
List all Authentication Methods of a Specific Application

This method returns information about all the authentications methods of a specific application.
■ Audit Users
URL
Note:
{AppID}/Authentications

Parameter AppID
Type String
Description The name of the application for which information about the authentication
methods are returned.
HTTP method GET

Header parameter
Type String
Body parameters
None
Result
{
"authentication":[
{
"AllowInternalScripts":<bool>,
"AppID":"<string>",
"AuthID":"<authID>",
"AuthType":<machineAddress/osUser/path/hashValue>,
"AuthValue":"<string>",
"Comment":"<string in case of hash authentication, else null>",
"IsFolder":"<string in case of path authentication, else null>"
}
]
}
Return Codes
Status code 200
Delete a Specific Application

This method deletes a specific application.
The user requires the following permission in the Vault:
■ Manage Users
URL
Note:

216 Applications
{AppID}/

Parameter AppID
Type String
Description The name of the application that will be deleted.
HTTP method DELETE
Header parameter
Type String
Body parameters
None
Result
{
}
Return Codes
Status code 200
Add Authentication
This method adds a new authentication method to a specific application in the Vault.
The user who adds this authentication method requires the following permissions in the Vault:
■ Manage Users

URL
Note:
{AppID}/Authentications/

Parameter AppID
Type String
Description The name of the application for which the user is adding a new
authentication method.
HTTP method POST
Header parameter
Type String
Body parameters
The web service parameters depend on the type of authentication specified in the URL.

218 Applications
For Path authentication:
{
"authentication":{
"AuthType":path,
"AuthValue":"<Path string>",
"IsFolder":<true/false>,
"AllowInternalScripts":<true/false>
}
}
Parameter AuthType (mandatory)
Type String
Description The type of authentication.
Valid values machineAddress/osUser/path/hashValue
Parameter AuthValue (mandatory)
Type String
Description The content of the authentication.
Valid values -
Parameter IsFolder
Type Boolean
Description Relevant for Path authentication only.
Default false
Parameter AllowInternalScripts
Type Boolean
Description Relevant for Path authentication only.
Default false
For Hash authentication:
{
"authentication":{
"AuthType":hash,
"AuthValue":"<Hash string>",
"Comment":"<Comment>",
}
}

Type String
Type String
Valid values -
Parameter Comment
Type String
Description Relevant for Hash authentication only.
Valid values Text
For OS user authentication:
{
"authentication":{
"AuthType":osUser,
"AuthValue":"<OS User Name>"
}
}
Type String
Type String
Valid values -

220 Applications
For Address authentication (allowed machines):
{
"authentication":{
"AuthType":machineAddress,
"AuthValue":"<machine address>"
}
}
Type String
Type String
Valid values -
For Certificate Serial Number authentication:
{
"authentication":{
"AuthType":"certificateserialnumber",
"AuthValue":"<certificate serial number string>",
"Comment":"<comment>",
}
}
Type String
Valid values certificateserialnumber
Type String
Valid values Valid positive or negative hex value
Parameter Comment
Type String

Description Any comment about this logon.
Valid values Text
Result
{
}
Return Codes
Status code 201
Description Authentication was added successfully

222 Applications
Delete a Specific Authentication

This method deletes a specific authentication method from a defined application.
The user requires the following permission in the Vault:
■ Manage Users
URL
Note:
{AppID}/Authentications/{AuthID}

Parameter AppID
Type String
Description The ID of the application in which the authentication method will be deleted.
Parameter AuthID
Type Integer
Description The unique ID of the specific authentication.
HTTP method DELETE
Header parameter
Type String
Body parameters
None

Result
{
}
Return Codes
Status code 200

224 Monitor Sessions
Monitor Sessions
Get Recordings
This method returns the details of recordings of PSM, PSMP or OPM sessions.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/API/Recordings?Limit=
{#}&Sort={Recording property}&offset={#}&Search={Search text}&Safe=
{Search text}&FromTime={UTC}&ToTime={UTC}&Activities={text}
The following values can be added in the URL. None of them are mandatory.
Parameter Limit
Type Integer
Description Determines the number of recordings that are returned in the list.
The maximum value is defined in the MaxRecords property in Options à
Privileged Session Management à General Setting à Search Properties.
Valid values A positive value greater than 0
Default 25
Parameter Sort
Type String
Description The sort can be done by each property on the recording file:
■ RiskScore
■ FileName
■ SafeName
■ FolderName
■ PSMVaultUserName
■ FromIP
■ RemoteMachine
■ Client
■ Protocol
■ AccountUserName

■ AccountAddress
■ AccountPlatformID
■ PSMStartTime
■ TicketID
The sort can be in ascending or descending order. To sort in descending
order, specify "-" (dash) before the recording property by which to sort.
Default Descending according to StartTime
Parameter Offset
Type Integer
Description Determines which recording results will be returned, according to a specific

place in the returned list. This value defines the recording's place in the list
and how many results will be skipped.
Default 0
Parameter Search
Type String
Description Returns recordings that are filtered by properties that contain the specified
search text.
Parameter Safe
Type String
Description Returns recordings from a specific Safe.
Parameter FromTime
Type Integer
Description Returns recordings from a specific date.
Parameter ToTime
Type Integer
Description Returns recordings before a specific date.
Parameter Activities
Type String
Description Returns recordings with specific activities.
HTTP method GET

Header parameter
Type String
Body parameters
None
Result
"Recordings": [
{
"SessionID": "<the session id>",
"SessionGuid": "<the session guide>",
"SafeName": "<the safe name>",
"FolderName": "<the folder name>",
"FileName": "<the file name>",
"Start": <the start date in unix time>,
"End": <the end date in unix time>,
"Duration": <the duration>,
"User": "<the use name>",
"RemoteMachine": "<the remote machine>",
"ProtectionDate": <the protection date in unix time>,
"ProtectedBy": "<the protected by user name>",
"ProtectionEnabled": <indication if the protection is enable>,
"AccountUsername": "<the account user name>",
"AccountPlatformID": "<the account platform ID>",
"AccountAddress": "<the account address>",
"PIMSuCommand": "<the PIMSU command>",
"PIMSuCWD": "<the PIMSU current working directory>",
"ConnectionComponentID": "<the connection component ID>",
"TicketID": "<the ticket ID>",
"FromIP": "<The IP address where the account was used>",
"Protocol": "<The protocol where the account was used>",
"Client": "<the client where the account was used>",
"RiskScore": <the risk score>,
"Severity": "<the savirity>",
"RecordingFiles": [
{
"FileName": "<The recording file name>",
"RecordingType": "<The recording type>",

"LastReviewBy": "<The recording reviewer username>",

"LastReviewDate": "<The review date in unix time>",
"FileSize": "<The recording file size>",
"CompressedFileSize": "<The recording compressed file size>",
"Format": ""<The recording format>""
},
...
]
"IncidentDetails": {
"Incident": {
"Id": "<The incident id>",
"Url": "<The incident URL in PTA>",
"Score": <The incident score>,
"Name": "<The incident description>",
"StartDate": <The incident start date in unix time>
},
"Sessions": [
{
"Id": "<The session id>",
"Score": <The session score>,
"Severity": "<The session severity>",
"Commands": [
{
"Value": "<The command>",
"Offset": "<The command offset>",
"Score": <The command scort>,
"Severity": "<The command severity>"
},
...
]
},
...
]
},
...
]
Parameter SessionID
Type String
Description The ID's of the Safe and File where the specific recording session file
was saved. format: "<safeId>_<fileId>".
Parameter SessionGuid
Type String
Description The GUID of the session file.
Parameter SafeName
Type String

Description The name of the Safe where the specific recording was saved.
Parameter FolderName
Type String
Description The name of the folder where the specific recording was saved.
Parameter FileName
Type String
Description The name of the specific session file.
Parameter Start
Type Integer
Description The start date and time, in unix time, when the privileged session took
place.
Parameter End
Type Integer
Description The end date and time, in unix time, when the privileged session took
place.
Parameter Duration
Type -
Description The duration of the recording, in the following format: HH:MM:SS
Parameter User
Type String
Description The name of the user who performed the connection.
Parameter RemoteMachine
Type String
Description The IP address of the remote machine that was accessed.
Parameter ProtectionEnabled
Type Boolean
Description Whether or not a recording can be deleted automatically after the Safe
retention period on the Recordings Safe has expired.
Parameter ProtectedDate
Type Integer
Description The date, in unix time, when the recording was set to be protected.
Parameter ProtectedBy
Type String

Description The user who is currently protecting the recording (so it will not auto-
purge after retention period).
Account details
Parameter AccountPlatformID
Type String
Description The ID of the platform that the used account is associated with.
Parameter AccountUsername
Type String
Description The name of the user who accessed the account. String
Type String
Description The address where the account was accessed.
PSM details
Type String
Description The PSM connection client
Parameter TicketID
Type String
Description The ID of the ticket entered when using Ticketing System for
connection.
Parameter FromIP
Type String
Description The IP address where the account was used.
Parameter Protocol
Type String
Description The protocol that was used for the connection.
Parameter Client
Type String
Description The connection client (RDP\SSH etc.) that used in the PSM server.
Security incidents received from PTA
Parameter RiskScore
Type String
Description The risk score that was given to the incidence. When there is no risk or
PTA doesn't scan the activity, the value is '-1'.

Parameter Severity
Type String
Description The severity of the highest risk activity in the session.
IncidentDetails → Incident - Only when an incident is received from PTA.
Parameter Id
Type String
Description The ID of the security incident
Parameter Name
Type Integer
Description The name of the security incident
Parameter Url
Type String
Description URL to the incident in PTA system
Parameter Score
Type
Description The risk score that was given to the incident.
Parameter StartDate
Type The start date and time, in unix time, of the security incident.
Description Integer
IncidentDetails → Sessions - Only when and incident is received from PTA.
Parameter Id
Type String
Description The unique ID of the security session in which the incident occured.
Parameter Score
Type Integer
Description The risk score that was given to the session.
Parameter Severity
Type String
IncidentDetails → Sessions → Commands
Parameter Value
Type String
Description The risky command.

Parameter Offset
Type String
Description
Parameter Score
Type The risk score that was given to the command.
Description Integer
Parameter Severity
Type String
Description The severity of the risky command.
TextRecording
Parameter FileName
Type String
Description The name of the text recording file.
Parameter RecordingType
Type Integer
Description The type of recording. Specify "0" for video.
Parameter LastReviewedBy
Type String
Description The name of the user who last reviewed it.
Parameter LastReviewedDate
Type Integer
Description The date when it was last reviewed, in unix time.
Parameter FileSize
Type Integer
Description The size of the text recording of the privileged session (in bytes). For
live sessions (size isn't final yet), there is no value.
Parameter CompressedFileSize
Type Integer
Description The size of the compressed text recording of the privileged session (in
bytes). For live sessions (size isn't final yet), there is no value.
Parameter Format
Type String
Description Text recording format.
VideoRecording

Parameter FileName
Type String
Description The name of the video recording file.
Type Integer
Description The type of recording file. Specify "1" for video.
Type String
Type Integer
Parameter FileSize
Type Integer
Description The size of the video recording of the privileged session (in bytes). For
Type The size of the compressed text recording of the privileged session (in
Description Integer
Parameter Format
Type String
Description Text recording format. For now we use unlt "VID" for video files.
OPM details
Parameter PIMSuCommand
Type String
Description Commands that run using PIMSu. Relevant for OPM sessions only.
Parameter PIMSuCWD
Type String
Description Current working directory. Relevant for OPM sessions only when
running PIMSu command.
Get Live Sessions

This method returns details of live sessions.

URL
Note:
http://<IIS_Server_Ip>/PasswordVault/API/LiveSessions?Limit=
{#}&Sort={Recording property}&offset={#}&Search={Search text}&Safe=
{Search text}&FromTime={UTC}&ToTime={UTC}&Activities={text}
Parameter Limit
Type Integer
Description Determines the number of lives sessions that are returned in the list.
The maximum value is defined in the MaxRecords property in Options à
Privileged Session Management à General Setting à Search Properties.
Default 25
Parameter Sort
Type String
Description The sort can be done by each property on the recording file:
■ RiskScore
■ FileName
■ SafeName
■ FolderName
■ PSMVaultUserName
■ FromIP
■ RemoteMachine
■ Client
■ Protocol
■ AccountUserName
■ AccountAddress
■ AccountPlatformID
■ PSMStartTime
■ TicketID
The sort can be in ascending or descending order. To sort in descending
order, specify "-" (dash) before the recording property by which to sort.
Default Descending according to StartTime
Parameter Offset
Type Integer

Description Determines which recording results will be returned, according to a specific

place in the returned list. This value defines the recording's place in the list
and how many results will be skipped.
Default 0
Parameter Search
Type String
Description Returns lives sessions that are filtered by properties that contain the
specified search text.
Parameter Safe
Type String
Description Returns lives sessions that use accounts from a specific Safe.
Parameter FromTime
Type Integer
Description Returns lives sessions from a specific date.
Parameter ToTime
Type Integer
Description Returns lives sessions before a specific date.
Parameter Activities
Type String
Description Returns lives sessions with specific activities.
HTTP method GET
Header parameter
Type String
Body parameters
None

Result
"Recordings": [
{
"SessionID": "<the session id>",
"SessionGuid": "<the session guide>",
"SafeName": "<the safe name>",
"FolderName": "<the folder name>",
"FileName": "<the file name>",
"Start": <the start date in unix time>,
"End": <the end date in unix time>,
"Duration": <the duration>,
"User": "<the use name>",
"RemoteMachine": "<the remote machine>",
"ProtectionDate": <the protection date in unix time>,
"ProtectedBy": "<the protected by user name>",
"ProtectionEnabled": <indication if the protection is enable>,
"AccountUsername": "<the account user name>",
"AccountPlatformID": "<the account platform ID>",
"AccountAddress": "<the account address>",
"PIMSuCommand": "<the PIMSU command>",
"PIMSuCWD": "<the PIMSU current working directory>",
"ConnectionComponentID": "<the connection component ID>",
"TicketID": "<the ticket ID>",
"FromIP": "<The IP address where the account was used>",
"Protocol": "<The protocol where the account was used>",
"Client": "<the client where the account was used>",
"RiskScore": <the risk score>,
"Severity": "<the savirity>",
"RecordingFiles": [
{
"FileName": "<The recording file name>",
"RecordingType": "<The recording type>",
"LastReviewBy": "<The recording reviewer username>",
"LastReviewDate": "<The review date in unix time>",
"FileSize": "<The recording file size>",
"CompressedFileSize": "<The recording compressed file size>",
"Format": ""<The recording format>""
},
...
]
"IncidentDetails": {
"Incident": {
"Id": "<The incident id>",
"Url": "<The incident URL in PTA>",
"Score": <The incident score>,
"Name": "<The incident description>",
"StartDate": <The incident start date in unix time>
},

"Sessions": [
{
"Id": "<The session id>",
"Score": <The session score>,
"Severity": "<The session severity>",
"Commands": [
{
"Value": "<The command>",
"Offset": "<The command offset>",
"Score": <The command scort>,
"Severity": "<The command severity>"
},
...
]
},
...
]
},
...
]
Parameter SessionID
Type String
Description The ID's of the Safe and File where the specific recording session file
was saved. format: "<safeId>_<fileId>".
Parameter SessionGuid
Type String
Description The GUID of the session file.
Parameter SafeName
Type String
Description The name of the Safe where the specific recording was saved.
Parameter FolderName
Type String
Description The name of the folder where the specific recording was saved.
Parameter FileName
Type String
Description The name of the specific session file.
Parameter Start
Type Integer
Description The start date and time, in unix time, when the privileged session took

place.
Parameter End
Type Integer
Description The end date and time, in unix time, when the privileged session took
place.
Parameter Duration
Type -
Description The duration of the recording, in the following format: HH:MM:SS
Parameter User
Type String
Description The name of the user who performed the connection.
Parameter RemoteMachine
Type String
Description The IP address of the remote machine that was accessed.
Parameter ProtectionEnabled
Type Boolean
Description Whether or not a recording can be deleted automatically after the Safe
retention period on the Recordings Safe has expired.
Parameter ProtectedDate
Type Integer
Description The date, in unix time, when the recording was set to be protected.
Parameter ProtectedBy
Type String
Description The user who is currently protecting the recording (so it will not auto-
purge after retention period).
Account details
Parameter AccountPlatformID
Type String
Description The ID of the platform that the used account is associated with.
Parameter AccountUsername
Type String
Description The name of the user who accessed the account. String

Type String
Description The address where the account was accessed.
PSM details
Type String
Description The PSM connection client
Parameter TicketID
Type String
Description The ID of the ticket entered when using Ticketing System for
connection.
Parameter FromIP
Type String
Description The IP address where the account was used.
Parameter Protocol
Type String
Description The protocol that was used for the connection.
Parameter Client
Type String
Description The connection client (RDP\SSH etc.) that used in the PSM server.
Security incidents received from PTA
Parameter RiskScore
Type String
Description The risk score that was given to the incidence. When there is no risk or
PTA doesn't scan the activity, the value is '-1'.
Parameter Severity
Type String
IncidentDetails → Incident - Only when an incident is received from PTA.
Parameter Id
Type String
Description The ID of the security incident
Parameter Name
Type Integer

Description The name of the security incident
Parameter Url
Type String
Description URL to the incident in PTA system
Parameter Score
Type
Description The risk score that was given to the incident.
Parameter StartDate
Type The start date and time, in unix time, of the security incident.
Description Integer
IncidentDetails → Sessions - Only when and incident is received from PTA.
Parameter Id
Type String
Description The unique ID of the security session in which the incident occured.
Parameter Score
Type Integer
Description The risk score that was given to the session.
Parameter Severity
Type String
IncidentDetails → Sessions → Commands
Parameter Value
Type String
Description The risky command.
Parameter Offset
Type String
Description
Parameter Score
Type The risk score that was given to the command.
Description Integer
Parameter Severity
Type String
Description The severity of the risky command.

TextRecording
Parameter FileName
Type String
Description The name of the text recording file.
Type Integer
Description The type of recording. Specify "0" for video.
Type String
Type Integer
Parameter FileSize
Type Integer
Description The size of the text recording of the privileged session (in bytes). For
Type Integer
Description The size of the compressed text recording of the privileged session (in
Parameter Format
Type String
Description Text recording format.
VideoRecording
Parameter FileName
Type String
Description The name of the video recording file.
Type Integer
Description The type of recording file. Specify "1" for video.
Type String

Type Integer
Parameter FileSize
Type Integer
Description The size of the video recording of the privileged session (in bytes). For
Type The size of the compressed text recording of the privileged session (in
Description Integer
Parameter Format
Type String
Description Text recording format. For now we use unlt "VID" for video files.
OPM details
Parameter PIMSuCommand
Type String
Description Commands that run using PIMSu. Relevant for OPM sessions only.
Parameter PIMSuCWD
Type String
Description Current working directory. Relevant for OPM sessions only when
running PIMSu command.
Return Codes
Status code
Description

Terminate a Session
This method enables the system to terminate an active PSM session immediately to
prevent high-risk activities.
URL
Note:
https://<Server>:<port>/PasswordVault/API/LiveSessions/<LiveSessionId>/Terminate

Parameter LiveSessionsId
Type String
Description The unique ID of the PSM Active Session.
Valid values -
Parameter Action
Type String
Description The action that will be triggered by this method.
Valid values Terminate
HTTP method POST
Header parameter
Type String

Body parameters
{
}
Add any other result details here
Return Codes
Status 200
code
Description OK
This indicates that this method was triggered with the Session ID in UUID
format.
Status 200
code
Description OK
This indicates that this method was triggered with a Session ID that was
already used to run this method.
Status 400
code
Description Bad Request

The UUID specified in this method is not according to UUID format (32
chars).
Status 401
code
Description Unauthorized
The REST API was called with a token that is invalid due to its length.
Status 401
code
The REST API was called with a token that is invalid as it contains a space.
Status 401
code
The REST API was called with an expired token.
Status 403
code
This method was called without a token.

Status 403
code
This method was called without an Authorization header.
Status 403
code
The REST API was called with a token that is not a valid base-64 string, for
one of the following reasons:
It contains a non-base-64 character
It contains more than two padding characters
It contains an illegal character among the padding characters
Status 403
code
The Vault user must be allowed to terminate the session according to
'Terminating Live Sessions Users and Groups' definitions. If the PTA sends
a request to terminate a session, only the PTAAppUser or PTAUser can run
this REST API.
Status 403
code
The Vault user must be allowed to suspend or resume the session

according to 'Suspending Live Sessions Users and Groups' definitions. If
the PTA sends a request to suspend a session, only the PTAAppUser or
PTAUser can run this REST API.
Status 403
code
The REST API was called, although the AllowPSMNotifications
parameter is set to 'No'.
Status 404
code
Description Not Found

This method was called with the wrong Web Service name.
Status 500
code
Description Internal server error

The system cannot run this method as the PSMNotifications Safe does not
exist.
Status 500
code


The system cannot run this method as the SessionControl file does not
exist in the PSMNotifications Safe.
Status 500
code

The system cannot run this method as it cannot connect to the Vault
Suspend/Resume a Session
This method enables the system to suspend or resume PSM sessions with either of the
following actions:
Action The system will ...
Suspend Prevent a user from interacting with an active session until a security manager
resumes it. This allows security teams to review the potentially risky
session's audit trail to determine whether or not to allow the privileged user to
continue their work.
Resume Resume the suspended active session and allow the privileged user to
continue working.
.
URL
Note:
https://<Server>:<port>/PasswordVault/API/LiveSessions/<LiveSessionId>/<Action>

Parameter LiveSessionsId
Type String
Description The unique ID of the PSM Active Session.
Valid values -
Parameter Action
Type String
Description The action that will be triggered by this method.
Valid values Suspend, Resume

HTTP method POST
Header parameter
Type String
Body parameters
{
}
Add any other result details here
Return Codes
Status 200
code
Description OK
This indicates that this method was triggered with the Session ID in UUID
format.
Status 200
code
Description OK
This indicates that this method was triggered with a Session ID that was
already used to run this method.
Status 400
code
Description Bad Request

The UUID specified in this method is not according to UUID format (32
chars).
Status 401
code
The REST API was called with a token that is invalid due to its length.

Status 401
code
The REST API was called with a token that is invalid as it contains a space.
Status 401
code
The REST API was called with an expired token.
Status 403
code
This method was called without a token.
Status 403
code
This method was called without an Authorization header.
Status 403
code
The REST API was called with a token that is not a valid base-64 string, for
one of the following reasons:
It contains a non-base-64 character
It contains more than two padding characters
It contains an illegal character among the padding characters
Status 403
code
The Vault user must be allowed to terminate the session according to
'Terminating Live Sessions Users and Groups' definitions. If the PTA sends
a request to terminate a session, only the PTAAppUser or PTAUser can run
this REST API.
Status 403
code
The Vault user must be allowed to suspend or resume the session

according to 'Suspending Live Sessions Users and Groups' definitions. If
the PTA sends a request to suspend a session, only the PTAAppUser or
PTAUser can run this REST API.
Status 403
code

248 Event Security
The REST API was called, although the AllowPSMNotifications

parameter is set to 'No'.
Status 404
code
Description Not Found

This method was called with the wrong Web Service name.
Status 500
code

The system cannot run this method as the PSMNotifications Safe does not
exist.
Status 500
code

The system cannot run this method as the SessionControl file does not
exist in the PSMNotifications Safe .
Status 500
code

The system cannot run this method as it cannot connect to the Vault
Event Security
Get Security Events

This method returns all PTA Security Events.
URL
Note:
https://<PTA_Server_host:Port>/API/Events/

HTTP method GET
Header parameter
Type String
Description The JWT token that identifies the session.
Valid A session token that was returned from the “Logon” method.
values
Parameter lastUpdatedEventDate
Type Number
Description The starting date to get the security events from (calculated by the number
of seconds since 1970).
Valid
values
Body parameters
None
Result
Note:
This is an example of the result for an array of events.
[
{
"id": "5accdf736e227a21e4d58bc6",
"type": "PSMRiskyCommand",
"score": 81,
"createTime": 1523375983000,
"lastUpdateTime": 1523375983000,
"audits": [
{
"id": "5accdf736e2282449296961c",
"type": "PSM_SSH_COMMAND",
"sensorType": "VAULT",
"action": "PSM Command",

250 Event Security
"psmCommand": "kill me",

"createTime": 1523375983000,
"vaultUser": "Administrator",
"account": {
"accountAsStr": "root@ca-dev-dc1.cyber-ark.co.il",
"type": "LOCAL_UNIX",
"account": {
"mTarget": {
"mOriginalAddress": "10.1.8.10",
"mResolvedAddress": {
"mAddress": "10.1.8.10",
"mHostName": "ca-dev-dc1",
"mFqdn": "ca-dev-dc1.cyber-ark.co.il"
}
},
"mUser": "root"
}
},
"source": {
"mOriginalAddress": "10.1.28.150"
},
"target": {
"mOriginalAddress": "10.1.8.10",
"mResolvedAddress": {
"mAddress": "10.1.8.10",
"mHostName": "ca-dev-dc1",
"mFqdn": "ca-dev-dc1.cyber-ark.co.il"
}
}
}
],
"additionalData": {
"mitigationAction": "termination",
"sessionIsLive": "false",
"matchPatterns": "kill(.*)",
"sessionIDs": [
"1f3b57b1-577d-42f2-bab0-4949e00615c1"
]
}
}
]
Parameter id
Type String
Description Event ID
Parameter type
Type String

Description Event type
Parameter score
Type Integer
Description Event score
Parameter createTime
Type Double
Description The creation date of the event (represented in seconds)
Parameter lastUpdateTime
Type Double
Description The last time the event was updated (represented in seconds)
Parameter audits
Type Array
Description Array of audits for the event
audits
Parameter id
Type String
Description Audit ID
Parameter type
Type String
Description Audit type
Parameter sensorType
Type String
Description The type of the sensor that sent the audit
Parameter action
Type String
Description The action of the audit. For example, Vault retrieve password, Vault logon,
PSM risky command , and so on
Parameter psmCommand
Type String
Description The risky activity
Parameter createTime
Type Double
Description The creation date of the audit

252 Event Security
Parameter vaultUser
Type String
Description The Vault user who triggered the session
Parameter account
Type
Description The account used in the session
account
Parameter accountAsStr
Type String
Description String representation of the account used in the session
Parameter type
Description String
Description Account type
Parameter account
Type
Description Detailed account information
Parameter mtarget
Type String
Description Detailed target account information
mtarget
Parameter mOriginalAddress
Type String
Description The original address of the target machine
Parameter mResolvedAddress
Type
Description The resolved address obof the target machineject
mResolvedAddress
Parameter mAddress
Type String
Description The address of the target machine
Parameter mHostName
Type String
Description The host name of the target machine

Parameter mFqdn
Type String
Description The Fqdn of the target machine
account
Parameter source
Type String
Description The source of the audit
source
Type String
Description The original address that was sent as a source
Type
Description The resolved address object
mResolvedAddress
Parameter mAddress
Type String
Description The original address
Parameter mHostName
Type String
Description The host name representation of the source address
Parameter mFqdn
Type String
Description The Fqdn representation of the source address
account
Parameter target
Type String
Description The target address of the audit
target
Type String
Description The original target address of the audit

254 Event Security
Type
Description The resolved target address as an object
mResolvedAddress
Parameter mAddress
Type String
Description The original target address
Parameter mHostName
Type String
Description The host name representation of the target address
Parameter mFqdn
Type String
Description The Fqdn representation of the target address
Parameter additionalData
Type String
Description The additional data
additionalData
Parameter mitigationAction
Type String
Description The mitigation action of the session, either terminate or suspend
Parameter sessionIsLive
Type String
Description True or false indicator of whether the session is live
Parameter matchPatterns
Type String
Description
Parameter sessionIDs
Type Array of strings
Description The session ID

System Health
Privileged Account Security's System Health provides the Vault administrator with a high
level report of the health status of the different CyberArk components in PAS and AIM
environments.
Note:
The System Health overview is relevant for active-passive, on-prem deployments and
Distributed Vaults deployments.
The information returned by the REST APIs does not include built-in users or custom
user types.
System Details
This method returns details about specific components and all their installed instances,
and system health information for each one.
URL
Note:
Ip>/PasswordVault/api/ComponentsMonitoringDetails/
{ComponentID}

Parameter ComponentID
Type String
Description The type of component for which data will be retrieved.
Valid values PVWA/SessionManagement/CPM/AIM
Example:
https://<IIS_Server_Ip>/api/ComponentsMonitoringDetails/PVWA
HTTP method GET

256 System Health
Header parameter
Type String
values BASE 64.
Result
{
"ComponentsDetails": [
{
"ComponentIP": "<ComponentIP>",
"ComponentUserName": "<ComponentUserName>",
"ComponentVersion": "<ComponentVersion>,
"ComponentSpecificStat": <details>
"IsLoggedOn": <true/false>,
"LastLogonDate": "<timestamp>"
},
]
}
Parameter ComponentIP
Type String
Description The IP of the component server.
Parameter ComponentUserName
Type String
Description The user name of the component, as recognized by the Vault.
Parameter ComponentVersion
Type String
Description The version number of the installed component's instance.
Parameter ComponentSpecificStat
Type Integer
Description Component specific information. Currently this is not supported and will
always return '-1'.
Parameter IsLoggedOn
Type Boolean

Description Whether or not the component is connected to the Vault.
Parameter LastLogonDate
Type The last date/time when the component logged onto the Vault server.
Description Date
Return Codes
Status 200
code
Description This action was completed successfully
Status 400
code
Description The action could not be completed.
Status 500
code
Description ITATP069E Error getting component status details. (Diagnostic Info:

<details>)
System Summary
This method returns consolidated information about the Vault, PVWA, CPM,
PSM/PSMP, and AIM, including all clients that are relevant to each specific component.
URL
Note:
https://<IIS_Server_Ip>/PasswordVault/api/ComponentsMonitoringSummary
HTTP method GET
Header parameter
Type String

258 System Health
Valid values A session token that was returned from the “Logon” method, .
Result
For PVWA, CPM, PSM/PSMP, and AIM:
{
"Components": [
{
"ComponentID": "<ComponentID>",
"ComponentName": "<ComponentName>",
"Description": "<Description>",
"ConnectedComponentCount": <number>,
"ComponentTotalCount": <number>,,
"ComponentSpecificStat": <number>,
}
]
Parameter ComponentID
Type String
Description The ID of the component whose details are displayed.
Parameter ComponentName
Type String
Description The name of the component whose details are displayed.
Type String
Description The type of information that will be displayed based on the relative
component.
PVWA - active users
CPM - managed accounts
PSM/PSMP - concurrent sessions
AIM Credential Provider - application IDs
Parameter ConnectedComponentsCount
Type The number of logged on component users for the relative component.
Description Integer
Parameter ComponentTotalCount
Type Integer
Description The total number of component users for the component type in the Vault.

Parameter ComponentSpecificStat
Type Integer
Description Component type specific information:

PVWA - Number of active users
CPM - Number of managed accounts
PSM/PSMP - Number of concurrent sessions
AIM Crededntial Provider - Number of application IDs
For Vaults:
"Vaults": [
{
"IP": "<IP>",
"Role": "<Role>",
"IsLoggedOn": <true/false>
}
]
Parameter IP
Type String
Description The IP of the Vault server.
Parameter Role
Type String
Description The role of the Vault.

In on-prem, active-passive deployments, one of the following values is
displayed:
Primary
DR
In Distributed Vaults deployments, one of the following values is displayed:
Master
DR
Parameter IsLoggedOn
Type Boolean
Description Whether or not the component user is currently logged on to the Vault and
replicating to the DR Vault.
Return Codes
Status 200
code

260 System Health
Description This action was completed successfully
Status 500
code
Description ITATP068E Error getting component status summary. (Diagnostic Info:

<details>)

Usage Examples
This section provides you with two usage examples:

Example 1: Listing Account ACLs
Example 2: Adding an Application/Authentication
Example 1: Listing Account ACLs

The following example shows how the PAS Web Services Access SDK can be
implemented in C# to list account ACLs.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Net;
using System.IO;
using System.Web.Script.Serialization;
namespace ConsoleApplication4
{
class OpmRestExmpl
{
static void Main(string[] args)
{
// Consts
//=======
const string JSON_CONTENT_TYPE =
"application/json";
const string VERB_METHOD_POST = "POST";
const string VERB_METHOD_GET = "GET";
const string JSON_SESSION_TOKEN_HEADER =

262 Example 1: Listing Account ACLs
"CyberArkLogonResult";
const string JSON_GET_ACCOUNT_RES_HEADER =
"ListAccountPrivilegedCommandsResult";
const string HTTP_SESSION_TOKEN_HEADER =
"Authorization";
// PIM Fields
const string POLICY_ID = "UnixSSH";
const string ACCOUNT_ADDRESS = "10.10.10.10";
const string ACCOUNT_USERNAME = "root";
const string ACCOUNT_USERNAME = "root";
const string ACCOUNT_ID = ACCOUNT_ADDRESS + "|" +
ACCOUNT_USERNAME + "|" + POLICY_ID;
// Uri
const string PVWA_WS_URI =
@"https://myServ.org.com/PasswordVault/WebServices";
const string LONGON_AUTHENTICATION_URI = PVWA_
WS_URI + @"/auth/cyberark/CyberArkAuthenticationService.svc/logon";
const string LOGOFF_AUTHENTICATION_URI = PVWA_
WS_URI +
@"/auth/cyberark/CyberArkAuthenticationService.svc/logoff";
const string ACCOUNT_ACL_URI = PVWA_
WS_URI + @"/PIMServices.svc/Account/" + ACCOUNT_ID +
"/PrivilegedCommands";
// Variables
//===========
// HTTP objects
WebRequest restRequest;
WebResponse restResponse;
// For JSON serialization
JavaScriptSerializer jsonSerializer = new
JavaScriptSerializer();
// Workflow objects
string sessionToken = null;
object[] AccountAcls;
// Workflow
//===========
// 0. Get Credentials from user:

Console.WriteLine("Enter Username:");
string user = Console.ReadLine();
Console.WriteLine("Enter Password:");
string pass = Console.ReadLine();
string connectionString = "{\"username\":\"" + user +
"\",\"password\":\"" + pass + "\"}";
// 1. Get the token
try
{
restRequest = WebRequest.Create(LONGON_
AUTHENTICATION_URI); // the uri.
restRequest.Method = VERB_METHOD_POST; // We
post the user&pass to retrieve the token, so we declare it.
restRequest.ContentType = JSON_CONTENT_TYPE; //

set to json - necessary for serialization & deserialization of the

content
// add the user&pass to packet data.
using (Stream requestStream =
restRequest.GetRequestStream())
{
byte[] inputStringBytes = Encoding.UTF8.GetBytes
(connectionString);
requestStream.Write(inputStringBytes, 0,
inputStringBytes.Length);
}
using (restResponse = restRequest.GetResponse())
{
using (Stream responseStream =
restResponse.GetResponseStream())
{
// Read the response stream from the http
header.
StreamReader rdr = new StreamReader
(responseStream, Encoding.UTF8);
string rawJsonSessionToken = rdr.ReadToEnd();
// verify that it returned a result.
if (string.IsNullOrEmpty(rawJsonSessionToken))
throw new Exception("session token was not
created");
// deserialize the json and take the value
from it.
deserializedJsonDictionary =
(Dictionary<string, object>)jsonSerializer.DeserializeObject
(rawJsonSessionToken);
sessionToken =
(string)deserializedJsonDictionary[JSON_SESSION_TOKEN_HEADER];
// verify that the result isn’t empty.
if (string.IsNullOrEmpty(sessionToken))
throw new Exception("session token was not
created");
}
}
}
{
Console.WriteLine("An error occurred on Logon");
HandleError(ex);
return;
}
// 2. Make the request (for instance, retrieve all
account acls)
// note that GET operations do not hold their data
inside the content section
// but rather pass it via the uri.
try
{
restRequest = WebRequest.Create(ACCOUNT_ACL_URI); //

the uri.
restRequest.Method = VERB_METHOD_GET; // We
want to get all the acls so we use this verb (to add, we use
"PUT").
content
restRequest.Headers[HTTP_SESSION_TOKEN_HEADER] =
sessionToken; // we add the session token to each request.
{
{
header.
string rawJsonResult = rdr.ReadToEnd();
// verify that it returned a result.
if (string.IsNullOrEmpty(rawJsonResult))
throw new Exception("json result was not
created");
// deserialize the json and take the value
from it.
(rawJsonResult);
AccountAcls = (object
[])deserializedJsonDictionary[JSON_GET_ACCOUNT_RES_HEADER];
foreach (Dictionary<string, object> command in
AccountAcls)
{
Console.WriteLine("PrivilegedCommand: {0},
{1}, {2}",
command["Command"],
command["PermissionType"],
command["UserName"]);
}
}
}
}
catch (Exception ex)
{
Console.WriteLine("An error occured while getting
Acls");
HandleError(ex);
}
// 3. logoff
try
{
restRequest = WebRequest.Create(LOGOFF_

AUTHENTICATION_URI); // the uri.

restRequest.Method = VERB_METHOD_POST; // We
want to get all the acls, so we use this verb (to add, we use
"PUT").
content
sessionToken; // we add the session token to each request.
{
("");
}
{
{
header.
}
}
{
Console.WriteLine("An error occurred while
performing Logoff");
HandleError(ex);
}
private static void HandleError(Exception ex)
{
if (ex is WebException)
{
WebException wex = ex as WebException;
HttpWebResponse res = ((HttpWebResponse)
(wex.Response));
switch (res.StatusCode)
{
case HttpStatusCode.Forbidden:
Console.WriteLine("An Authentication error
occurred: " + res.StatusDescription);
break;
case HttpStatusCode.InternalServerError:
default:
Console.WriteLine("An error occurred: " +
res.StatusDescription);
break;

}
}
else
{
Console.WriteLine("An error occurred: " + ex.Message);
}
}
}
}

Example 2: Adding an Application/Authentication

The following example shows how the PAS Web Services Access SDK can be
implemented in C# to add an application and its authentication method.
using System
using System;using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Net;
using System.IO;
using System.Web.Script.Serialization;
namespace WebServiceSDKtest
{
class AIMRestExmpl
{
static void Main(string[] args)
{
//Constants
const string JSON_CONTENT_TYPE = "application/json";
const string VERB_METHOD_POST = "POST";
const string VERB_METHOD_GET = "GET";
const string JSON_SESSION_TOKEN_HEADER =
"CyberArkLogonResult";
const string HTTP_SESSION_TOKEN_HEADER =
"Authorization";
const string JSON_GET_ACCOUNT_RES_HEADER =
"application";
const string APPID = "WSTestApp8";
//URI information
const string PVWA_WS_URI =
@"http://192.168.2.13/PasswordVault/WebServices";
const string LOGON_AUTHENTICATION_URI = PVWA_WS_URI +
@"/auth/CyberArk/CyberArkAuthenticationService.svc/logon";
const string LOGOFF_AUTHENTICATION_URI = PVWA_WS_URI +
@"/auth/CyberArk/CyberArkAuthenticationService.svc/logoff";
const string AIM_WS_ONE = PVWA_WS_URI +
@"/PIMServices.svc/Applications";
//Variables
WebRequest restRequest;
WebResponse restResponse;
JavaScriptSerializer jsonSerializer = new
JavaScriptSerializer();
Dictionary<string, object> deserializedJsonDictionary;
string SessionToken = null;
object[] ApplicationIds;
//Authentication Connection String Assembly
Console.WriteLine("Enter Vault Username:"); //Get

268 Example 2: Adding an Application/Authentication
username from user

Console.WriteLine("Enter Vault Password:"); //Get
Password from user
string pass = Console.ReadLine();
string ConnectionString = "{\"username\":\"" + user +
"\",\"password\":\"" + pass + "\"}";
//Token retrieval
try
{
restRequest = WebRequest.Create(LOGON_
AUTHENTICATION_URI); //Specifying URI
restRequest.Method = VERB_METHOD_POST;
restRequest.ContentType = JSON_CONTENT_TYPE;
restRequest.GetRequestStream
{
byte[] inputStringBytes =
Encoding.UTF8.GetBytes(ConnectionString);
}
using(restResponse = restRequest.GetResponse())
{
{
string rawJsonSessionToken = rdr.ReadToEnd
();
if(string.IsNullOrEmpty
(rawJsonSessionToken))
{
throw new Exception("Session Token
not created");
}
(rawJsonSessionToken);
SessionToken =
(string)deserializedJsonDictionary[JSON_SESSION_TOKEN_HEADER];
if(string.IsNullOrEmpty(SessionToken))
{
throw new Exception("session token was
not created");
}
}
}
}
{

Console.WriteLine("A Logon Error Has Occured");

HandleError(ex);
return;
}
//Create the AppID request
try
{
restRequest = WebRequest.Create(AIM_WS_ONE);
restRequest.ContentType= JSON_CONTENT_TYPE;
restRequest.Headers[HTTP_SESSION_TOKEN_HEADER]=
SessionToken;
string APPIDRequest = "{\"application\":{\"AppID\":\"" +
APPID + "\"}}";

{
(APPIDRequest);
}
{
{
(responseStream,Encoding.UTF8);
string response = rdr.ReadToEnd();
}
}
}
{
Console.WriteLine("Error occured creating
AppID");
HandleError(ex);
}
//List of existing AppIDs

try
{
restRequest = WebRequest.Create(AIM_WS_ONE);
restRequest.Method = VERB_METHOD_GET;
SessionToken;
{


{
if (string.IsNullOrEmpty(rawJsonResult))
throw new Exception("Json result was
not created");
(rawJsonResult);
ApplicationIds =
(object[])deserializedJsonDictionary[JSON_GET_
ACCOUNT_RES_HEADER];
foreach (Dictionary<string, object> AppID
in ApplicationIds)
{
Console.WriteLine("ApplicationID: {0}",
AppID["AppID"]);
}
}
}
}
{
Console.WriteLine("An error occured while
retrieving Application List");
HandleError(ex);
}
//Logoff
try
{
restRequest = WebRequest.Create(LOGOFF_
AUTHENTICATION_URI);
SessionToken;
{
byte[] inputStringBytes =
Encoding.UTF8.GetBytes("");
}

{
{
}
}
{
Console.WriteLine("An error occured while logging
off");
HandleError(ex);
}
}
private static void HandleError(Exception ex)
{
if (ex is WebException)
{
WebException wex = ex as WebException;
HttpWebResponse res = ((HttpWebResponse)
(wex.Response));
switch (res.StatusCode)
{
case HttpStatusCode.Forbidden:
Console.WriteLine("An
Authentication error occured: " + res.StatusDescription);
break;
case HttpStatusCode.InternalServerError:
default:
Console.WriteLine("An error occured: "
+ res.StatusDescription);
break;
}
}
else
{
Console.WriteLine("An Error Occured: " +
ex.Message);
}
}
}
}

Troubleshooting
Problem: A delete request was sent to the Vault, and the following response was received:
405 Method not allowed.
Solution: Uninstall WebDAV on the IIS.


Privileged Account Security Web Services SDK Implementation Guide PDF

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Privileged Account Security Web Services SDK Implementation Guide PDF

Caricato da

Copyright:

Formati disponibili

Privileged Account Security

Web Services SDK