Web Services SDK
Implementation Guide
Version 9.5
Copyright © 1999-2015 CyberArk Software Ltd. All rights reserved.
This document contains information and ideas, which are proprietary to CyberArk
Software Ltd. No part of this publication may be reproduced, stored in a retrieval system,
or transmitted, in any form or by any means, electronic, mechanical, photocopying,
recording, scanning, or otherwise, without the prior written permission of CyberArk
Software Ltd.
Table of Contents
What’s New?
3
Introduction
4
SDK Supported Platforms
5
Using the PAS Web Services SDK
5
API Commands
6
CyberArk Authentication
7
Logon
7
Logoff
8
Managing Accounts
9
Add Account
9
Get Account
13
Delete Account
15
Change Credentials
16
Update Account Details
18
Safe Methods
23
Add Safe
23
Update Safe
26
Delete Safe
29
Safe Members
30
Add Safe Member
30
Update Safe Member
33
Delete Safe Member
39
Policy/ACL Methods
40
List Policy/ACL
40
Add Policy/ACL
42
Delete Policy/ACL
44
Account/ACL Methods
45
List Account/ACL
45
Add Account/ACL
47
Delete Account ACL
50
Applications
51
List Applications
51
List a Specific Application
53
Add Application
55
List all Authentication Methods of a Specific Application
58
Add Authentication
59
Delete a Specific Application
63
Delete a Specific Authentication
64
Usage Examples
65
Example 1: Adding an ACL
65
Example 2: Adding an Application/Authentication
70
Privileged Account Security
What’s New?
Managing Accounts
Update Account Details - You can update an existing account's details. For more
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.
This chapter includes the following sections:
SDK Supported Platforms
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 request verb. 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 GET request, using the
following format:
http://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Account/
<AccountAdress>|<AccountUserName>|<AccountPolicyId>/PrivilegedCommands
For example:
http://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 request must contain an HTTP header field named Authorization that
contains the value of a session token received from the Logon activity.
The PAS Web Services can be accessed with any tool or language that enables you to
create HTTP requests and handle HTTP responses. For more information, refer to the
C# and Java examples in Usage Examples, page 65.
API Commands
This chapter introduces you to the Privileged Account Security API commands which
enable you to implement CyberArk’s Web Services SDK. It describes how to use them
and gives samples that show typical implementations.
It includes the following sets of API commands:
CyberArk Authentication
Managing Accounts
Safe Methods
Safe Members
Policy/ACL Methods
Account/ACL Methods
Note: For every Web Services call except for Logon, the request must include an HTTP header
field named Authorization, containing the value of a session token received from the Logon activity
CyberArk Authentication
Logon
Description:
This method authenticates a user to the Vault and returns a token that can be used in subsequent Web Services calls.URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/auth/ Cyberark/CyberArkAuthenticationService.svc/LogonNote: Make sure there are no spaces in the URL.
HTTP Method:
POSTParameters:
{"username":"<user_name>", "password":"<password>" }
The Logon syntax has these parts:
Parameter Type Description
Default
username string The name of the user logging on.
None
password string The password of the user logging on.
None
Result:
{"CyberArkLogonResult":"<Session_Token>" }
Parameter Type Description Default
CyberArkLogonResult string The session token that identifies the session. This token is used for every other web service in the same session.
None
Logoff
Description:
This method performs Logoff and removes the Vault session.URL
http://<IIS_Server_Ip>/PasswordVault/WebServices/auth/Cyberark/CyberArkAuthenticationService.svc/Logoff
Note: Make sure there are no spaces in the URL.
HTTP Method:
POSTHeader Input:
The following input parameter is required in the header:Parameter Type Description Valid Values
Authorization String The token that
identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
This method has no parameters.Result:
{}
Status Code: 200 Description: OK
Managing Accounts
Add Account
Description:
This method adds a new privileged account to the Vault.URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Account
Note: Make sure there are no spaces in the URL.
HTTP
Method:
POST
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
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"} ]
} }
The
Add
syntax has these parts:Parameter Type Description Valid
Values
safe String The Safe where the account will be created. This parameter is required.
Safe name
platformID String The platform assigned to this account.
This parameter is required.
Platform ID
address String The name or address of the machine where the account will be used.
Machine name or address
account Name String The name of the account. Account name
password String The password value. This parameter is required.
Password
username String The name of the user who will use the account on the target machine.
User name on the target machine groupName String The name of the group
with which the account will be associated .
Group name
groupPlatformID String The ID of the platform that manages the account group.
Group platform ID
disableAutoMgmt Boolean Whether or not automatic management will be disabled for this account. Default=”false”
true/false
disable AutoMgmt Reason
String The reason why the account was disabled for auto-management. This parameter is only relevant if
disableAutoMgmt is set to “true”.
dynamic Properties
List List of name=value pairs
Parameter Type Description Valid Values
ExtraPass1Name String The name of the logon account.
Logon account ExtraPass1Folder String The folder where the
logon account is stored. Default="Root"
Folder
ExtraPass1Safe String The Safe where the logon account is stored.
Safe name
ExtraPass3Name String The name of the reconcile account.
Reconcile account ExtraPass3Folder String The folder where the
reconcile account is stored.
Default="Root"
Folder
ExtraPass3Safe String The Safe where the reconcile account is stored. Safe name
Result:
{ } Status Code: 201Get Account
Description:
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:
Retrieve account
Notes
:This method does not display the actual password.
If ten or more accounts are found, the Count Output parameter will show 10.
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/AccountsNote: Make sure there are no spaces in the URL.
HTTP
Method:
GET
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Query
Parameters:
The following parameters can be specified in the URL to filter the result:
Parameter Type Description Valid
Values
Keywords String Specify a keyword to search for. If you specify multiple keywords, the search will include all the
keywords. Separate keywords with a space. Multiple keywords. Maximum of 500 characters.
Safe String 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.
Maximum of 28 characters
The following example shows how to retrieve an account with address:
10.10.1.1
, user:root
, Safe: calledUNIXAccountsSafe
./PasswordVault/WebServices/PIMServices.svc/Accounts?
Keywords=10.10.1.1%2C%20root&Safe=%5EUNIXAccountsSafe%5Cd
Result:
{"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>"} ]
} ] }
Status Code: 200
The following table explains the output parameters:
Parameter Type Description
Count Integer The number of accounts that were found by the requested query.
AccountID Integer The account`s unique ID.
Safe String The name of the Safe where the account is stored.
Folder String The name of the folder where the account is stored.
Name String The name of the account.
-Delete Account
Description:
This method deletes a specific account in the Vault.The user who runs this web service requires the following permission in the Vault:
Delete accounts
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Accounts/{AccountID}The following information is required to replace {AccountID}:
Parameter Type Description Valid
Values
AccountID Number The unique ID of the account to delete. This is retrieved by the Get Account web service.
Account ID
Note: Make sure there are no spaces in the URL.
HTTP
Method:
DELETE
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
{ }Result:
{ } Status Code:200Description: Account was deleted successfully
Change Credentials
Description:
This method initiates 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:
http://<IIS_Server_Ip>//PasswordVault/WebServices/PIMServices.svc/Accounts/{AccountID} /ChangeCredentials
The following information is required to replace {AccountID}:
Parameter Type Description Valid Values
AccountID Number The unique account ID of the account to change. This is retrieved by the Get Account web service.
Account ID
Note: Make sure there are no spaces in the URL.
HTTP Method:
PUTHeader Input:
The following input parameter is required in the header:Parameter Type Description Valid Values
Authorization String The token that identifies the session. A session token that was returned from the “Logon” method.
Parameters:
{ ImmediateChangeByCPM ChangeCredsForGroup }Parameter Type Description Valid Values ImmediateChange ByCPM String Whether or not the account will be immediately changed by the CPM. Specify Yes to initiate a password change by the CPM. Yes/No ChangeCredsFor Group String Whether or not to change the password in all accounts that belong to the 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. Default = Yes Yes/No
Result:
{ } Status Code 200Update Account Details
Description:
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.
Notes:
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:
http://<IIS_Server_IP>/PasswordVault/WebServices/ PIMServices.svc/Accounts/{AccountID}/Note: Make sure there are no spaces in the URL.
The following information is required to replace AccountID:
Parameter Type Description Valid
Values
AccountID Number The unique ID of the account to update. This is retrieved by the Get Account Service.
Account ID
HTTP
Method:
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the "Logon" method.
Query
Parameters:
The following parameters can be updated:
Parameter Type Description Valid Values
Folder String The folder where the account is stored.
Folder name
AccountName String The name of the account to update. Make sure the account name meets your enterprise account policy specifications. Account name
DeviceType String 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. Device type
PlatformID
String
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 Implementation Guide. Platform IDParameter Type Description Valid Values
Address String The new name or address of the machine where the account will be used.
Machine name or address
UserName - String The updated name of the user who will use the account on the target machine.
User name on the target machine
GroupName String 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.
Account group name
GroupPlatformID String GroupPlatformID is required when you want to move an account to a new group.
Group platform ID
Properties List List of name=value pairs.
Property name and value
Example:
In the following example all properties were sent with the original
value except for the account address, which will be updated from
1.1.1.1 to 10.10.10.10:
{
"Accounts": {
“Folder”: “Root”,
“AccountName”: “Operating System-WinDesktopLocal-1.1.1.1-Administrator”, “PlaformID":“WinDesktopLocal”, “DeviceType":“Operating System", “Address”: “10.10.10.10”, “UserName”:“Administrator” } }
In the following example, a new account group name was entered to
replace an existing account group name in the optional GroupName
field:
{
"Accounts": {
“Folder”:“Root”,
“AccountName”: “Operating System-WinDesktopLocal-1.1.1.1-Administrator”, “PlaformID":“WinDesktopLocal”, “DeviceType":“Operating System”, “Address”:“10.10.10.10”, “UserName":“Administrator”, “GroupName”:“ WindowsAccountGroup” } }
In the following example, department and geographical location
properties are added to an existing account with properties:
{
"Accounts": {
“Folder”:“Root”,
“AccountName”: “Operating System-WinDesktopLocal-1.1.1.1-Administrator”, “PlaformID":“WinDesktopLocal”, “DeviceType":“Operating System”, “Address”:“10.10.10.10”, “UserName":“Administrator”, “GroupName”:“ WindowsAccountGroup”, “Properties” : [{
“Key”: “ Department”, “Value”: “Finance"}, {“Key": “GeoLocation”, “Value”: “UK”}] }
Result:
{ }Status Code: 200
Description: Account was updated successfully
Safe Methods
Add Safe
Description:
This method adds a new Safe to the Vault.The user who runs this web service requires the following permission in the Vault:
Add Safes
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/SafesNote: Make sure there are no spaces in the URL.
HTTP
Method:
POST
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
{ "safe" : { "SafeName":"<Safe name>", "Description": "<Description>", "OLACEnabled": <true/false>, "ManagingCPM": "<CPM user>","NumberOfVersionsRetention":<1-999>,
"NumberOfDaysRetention":<1-3650>
} }The
Add
syntax has these parts:Parameter Type Description Valid
Values
SafeName String Name of a Safe to create. This parameter is required.
Specify up to 28 characters.
The following characters aren’t allowed: \/:*<>".| Do not start a Safe name with a space.
New Safe name
Description String Description of the new Safe. Up to 100 characters. OLAC
Enabled
Boolean Whether or not to enable Object Level Access Control for the new Safe.
true/false
Managing CPM
String The name of the CPM user who will manage the new Safe. An existing CPM user or “” to prevent the CPM from managing the Safe. NumberOf Versions Retention
Numeric 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.
Parameter Type Description Valid Values
NumberOf Days Retention
Numeric 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. 1-3650
Result:
{ "safe":{"SafeName":"<The name of the new Safe>", "Description":"<Description for the new Safe>", "OLACEnabled":<true/false>,
"ManagingCPM":”<Name of CPM user managing the Safe>”, "NumberOfVersionsRetention":<1-999>,
"NumberOfDaysRetention":<1-3650>, }
}
Status Code: 201
Description: Safe was added successfully.
Update Safe
Description:
This method updates a single Safe in the Vault. The user who runs this web service requires the following permission in the Vault:
Manager Safe
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/ PIMServices.svc/Safes/{SafeName}The following information is required to replace {SafeName}:
Parameter Type Description Valid
Values
SafeName String The name of the Safe to update.
Safe name
Note: Make sure there are no spaces in the URL.
HTTP
Method:
PUT
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
{"Safes":{
"SafeName":"<The name of the Safe>", "Description":"<Description of the Safe>", "OLACEnabled":<true/false>,
"ManagingCPM":”<Name of CPM user managing the Safe>”, "NumberOfVersionsRetention":<1-999>,
"NumberOfDaysRetention":<1-3650>, }
}
Parameter Type Description Valid
Values
SafeName String The name of the Safe to update.
Specify up to 28 characters.
The following characters aren’t allowed: \/:*<>".| Do not start a Safe name with a space.
Safe name.
Description String The updated description of the Safe.
Up to100 characters OLACEnabled Boolean Whether or not to enable
Object Level Access Control.
true/false
Managing CPM
String Name of the CPM user who will manage the Safe.
An existing CPM user or “” to prevent the CPM from managing the Safe. NumberOf Versions Retention
Numeric 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.
1-999
Parameter Type Description Valid Values
NumberOf Days Retention
Numeric 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. 1-3650
Result:
{ "Safes":{"SafeName":"<The name of the Safe>", "Description":"<Description for the Safe>", "OLACEnabled":<true/false>,
"ManagingCPM":”<Name of CPM user managing the Safe>”, "NumberOfVersionsRetention":<1-999>,
"NumberOfDaysRetention":<1-3650>, }
}
Delete Safe
Description:
This method deletes a Safe from the Vault.The user who runs this web service requires the following permission in the Vault:
Manage Safe
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/ PIMServices.svc/Safes/{SafeName}The following information is required to replace {SafeName}:
Parameter Type Description Valid Values
SafeName String The name of Safe to delete. Safe name
Note: Make sure there are no spaces in the URL.
HTTP
Method:
DELETE
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
{ }Result:
{ } Status Code 200Safe Members
Add Safe Member
Description:
This method adds an existing user as a Safe member.The user who runs this web service requires the following permission in the Vault:
Manage Safe Members
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/ PIMServices.svc/Safes/{SafeName}/MembersThe following information is required to replace {SafeName}:
Parameter Type Description Valid
Values
Safe name
String
The name of the safe to add a
member to.
Safe
name
Note: Make sure there are no spaces in the URL.
HTTP
Method:
POST
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the "Logon" Method.
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>}, ]
}
The
Add
syntax has these partsParameter Type Description Valid Values
MemberName String Vault or Domain user or group to add as a Safe member. This parameter is required.
Vault or domain user.
SearchIn String The Vault or Domain to search for the user or group to add as a Safe member. Default value = Vault.
Vault or the domains that are defined in the Vault.
Parameter Type Description Valid Values
Membership Expiration Date
String Defines when the member’s Safe membership expires. Specify “” for no expiration date.
Default = no expiration
Date format MM/DD/YY
Permissions The Safe member’s permissions in the Safe.
Permissions specified in the following table
Result:
{"member":{
"MemberName":"<The name of the Safe member who has just been added>",
"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> } } } Status Code: 201
Update Safe Member
Description:
This method updates an existing Safe member.The user who runs this web service requires the following permission in the Vault:
Manage Safe Members
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/ PIMServices.svc/Safes/{SafeName}/Members/{MemberName}
The following parameters should pass as input in the URL:
Parameter Type Description
SafeName String Name of the Safe to which the Safe member belongs.
MemberName String Vault/Domain user/group member to update.
Note: Make sure there are no spaces in the URL.
HTTP
Method:
PUT
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was resumed from the `Logon method`.
Parameters:
{"members":{
" 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>}, ]
} }
The
List
syntax has these parts:Parameter Type Description Valid
Values
MembershipExpirationDate String Defines when the user`s Safe membership expires. Specify “” for no
expiration date. Permissions User permission
in the Safe.
Permissions specified in the following table. Specify the following permissions:
Parameter Type Description Valid Values
UseAccounts
Boolean
Use accounts but not view passwords.true/false
RetrieveAccounts Boolean Retrieve and view accounts in the Safe.
true/false
ListAccounts Boolean View accounts list. true/false AddAccounts Boolean 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. true/false UpdateAccount Content
Boolean Update existing account content.
true/false
UpdateAccount Properties
Boolean Update existing account properties. true/false InitiateCPM Account Management Operations
Boolean Initiate password management
operations through CPM, such as changing passwords,
verifying and reconciling passwords. When this parameter
is set to false, the SpecifyNext AccountContent is automatically set to false.
true/false
Parameter Type Description Valid Values
SpecifyNext AccountContent
Boolean Specify the password that will be used when the CPM changes the password value. This parameter can only be specified when InitiateCPMAccount ManagementOperations is set to true. When InitiateCPMAccount ManagementOperations is set to false this parameter is
automatically set to false.
true/false
RenameAccounts Boolean Rename existing accounts in the Safe.
true/false
DeleteAccounts Boolean Delete existing passwords in the Safe
true/false
UnlockAccounts Boolean Unlock accounts that are locked by other users.
true/false
ManageSafe Boolean Perform administrative tasks
in the Safe, including: Update Safe properties Recover the Safe Delete the Safe
true/false
ManageSafe Members
Boolean Add and remove Safe members, and update their
authorizations in the Safe.
true/false
BackupSafe Boolean Create a backup of a Safe and its contents, and store in another location.
true/false
ViewAudit Log
Boolean View account and user activity in the Safe.
true/false
ViewSafe Members
Boolean View Safe members` permissions.
Parameter Type Description Valid Values
Requests Authorization Level
Numeric Requests Authorization Level. 0 – cannot authorize 1 – authorization level 1 2 – authorization level 2 0/1/2 Access Without Confirmation
Boolean Access the Safe without confirmation from authorized users. This overrides the
Safe properties that specify
that Safe members require confirmation to access the Safe.
true/false
CreateFolders Boolean Create folders in the safe true/false
DeleteFolders Boolean Delete folders from the safe
true/false
MoveAccounts AndFolders
Boolean Move accounts and folders in the Safe to different folders and subfolders.
true/false
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> } } } Status Code: 201
Delete Safe Member
Description:
This method removes a specific member from a Safe.The user who runs this web service requires the following permission in the Vault:
Manage Safe Members
URL:
http://<IIS_Server_Ip>/PasswordVault /WebServices/ PIMServices.svc/Safes/{SafeName}/Members/ {MemberName}The following URL parameters are required:
Parameter Type Description Valid
Values
SafeName String The name of the Safe from which to delete the member.
Safe name
Member Name
String The name of the Safe member to delete from the Safe’s list of members.
Vault user or domain user.
Note: Make sure there are no spaces in the URL.
HTTP
Method:
DELETE
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
{ }Result:
{ } Status Code: 200Policy/ACL Methods
List Policy/ACL
Description:
This method gets a list of the privileged commands (OPM rules) associated with this policy.URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Policy/{PolicyId}/PrivilegedCommandsThe following mandatory information is required to replace {PolicyID}:
Parameter Type Description
PolicyID String The ID of the policy for which the privileged commands will be listed.
Note: Make sure there are no spaces in the URL.
HTTP
Method:
GET
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
TheList
syntax has these parts:Parameter Type Description Valid
Values
PolicyId text The Policy Id provided in the URL.
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>"}, {…}, {…} ] } Status Code: 200 Description: OK
Add Policy/ACL
Description:
This method adds a new privileged command rule to the policy.URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Policy/{PolicyId}/PrivilegedCommands The following mandatory information is required to replace {PolicyID}:Parameter Type Description
PolicyID String The ID of the policy to which the new privileged command rule will be added.
Note: Make sure that there are no spaces in the URL.
HTTP Method:
PUTHeader Input:
The following input parameter is required in the header:Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was
returned from the “Logon” method.
Parameters:
{ "Command":"<Command>", "CommandGroup":<true/false>, "PermissionType":"<Allow/Deny>", "Restrictions":"<Restrictions>", "UserName":"<UserName>" }The
Add
syntax has these parts:Parameter Type Description Valid Values
Command text The command. Not empty Command Group bool Whether or not this is a command group. True/False Permission Type text Allow or Deny command. Allow/Deny
PolicyId text The Policy Id, provided in the URL. Not empty Restrictions text A restrictions string. <restrictionName> = <Value>;<… or empty
UserName text The user this rule applies to.
User name, or "*" for all users
Result:
{ "AddPolicyPrivilegedCommandResult": { "Command":"<command>", "CommandGroup":"<true/false>", "Id":"<number>", "IsGroup":"<true/false>", "Type":"<Policy/Account>", "PermissionType":"<Allow/Deny>", "PolicyId":"<policyID>","Restrictions":"<restrictions string, delimeted by ;>", "UserName":"<userName>"}
}
Status Code: 201
Description: Policy ACL was added successfully
Delete Policy/ACL
Description:
This method deletes all privileged commands rules associated with the policy.URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Policy/{PolicyId}/PrivilegedCommands/{Id}The following mandatory information is required to replace {PolicyID} and {Id}:
Parameter Type Description
PolicyID String The ID of the policy from which the privileged commands will be deleted.
Id String The ID of the command rule that will be deleted.
Note: Make sure there are no spaces in the URL.
HTTP
Method:
DELETE
Header Input:
The following input parameter is required in the header:Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
TheDelete
syntax has these parts:Parameter Type Description Valid
Values
PolicyId text The Policy Id provided in the URL.
Not empty
Id number The Rule Id provided in the URL.
Not empty
Result:
Status Code: 204 (empty content)Account/ACL Methods
List Account/ACL
Description:
This method gets a list of the privileged commands (OPM rules) associated with this account.URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Account/{AccountAddress}|{AccountUserName}|{AccountPolicyId}/PrivilegedCommands The following mandatory information is required to replace {AccountAddress}, {AccountUserName} and {AccountPolicyID}:
Parameter Type
Description
Account Address
String
The address of the account whose
privileged commands will be listed.
Account UserName
String
The name of the account’s user.
Account PolicyId
String
The Policy ID associated with this account.
Note: Make sure there are no spaces in the URL.
HTTP
Method:
GET
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
TheList
syntax has these parts:Parameter Type Description Valid
Values
AccountPolicyId text The Policy Id of the account provided in the URL. AccountAddress text The Address of the account
provided in the URL.
Not empty AccountUser
Name
text The User Name of the account provided in the URL.
Not empty
Result:
{ "ListAccountPrivilegedCommandsResult": [ {"Command":"<command>", "CommandGroup":"<true/false>", "Id":"<number>", "Type":"<Policy/Account>", "IsGroup":"<true/false>", "PermissionType":"<Allow/Deny>", "PolicyId":"<policyID>","Restrictions":"<restrictions string, delimeted by ;>", "UserName":"<userName>"}, {…}, {…} ] } Status Code: 200 Description: OK
Add Account/ACL
Description:
This method adds a new privileged command rule to the account.URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/PIMServices.svc/Account/{AccountAddress}|
{AccountUserName}|{AccountPolicyId}/PrivilegedCommands The following mandatory information is required to replace {AccountAddress}, {AccountUserName} and {AccountPolicyID}:
Parameter Type Description
Account Address
String The address of the account to which a new privileged command will be added.
Account UserName
String The name of the account’s user.
Account PolicyId
String The Policy ID associated with this account.
Note: Make sure there are no spaces in the URL.
HTTP
Method:
PUT
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
{ "Command":"<Command>", "CommandGroup":<true/false>, "PermissionType":"<Allow/Deny>", "Restrictions":"<Restrictions>", "UserName":"<UserName>" }The
Add
syntax has these parts:Parameter Type Description Valid Values
Account PolicyId
text The Policy Id of the account, provided in the URL.
Account Address
text The Address of the account, provided in the URL.
Not empty
Account UserName
text The User Name of the account, provided in the URL.
Not empty
Command text The command. Not empty Command
Group
bool Whether or not this is a command group.
True/False
PermissionType text Allow or Deny command.
Allow/Deny
Restrictions text A restrictions string. <restrictionName>= <Value>;<… or empty
UserName text The user this rule applies to.
User name, or "*" for all users
Result:
{ "AddAccountPrivilegedCommandResult": { "Command":"<command>", "CommandGroup":"<true/false>", "Id":"<number>", "IsGroup":"<true/false>", "Type":"<Policy/Account>", "PermissionType":"<Allow/Deny>", "PolicyId":"<policyID>","Restrictions":"<restrictions string, delimeted by ;>", "UserName":"<userName>"}
}
Status Code: 201
Description: Policy ACL added successfully.
Delete Account ACL
Description:
This method deletes privileged commands rules associated with the account.URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Policy/{PolicyId}/PrivilegedCommands/{Id}The following mandatory information is required to replace {PolicyID} and {Id}:
Parameter Type Description
PolicyID String The ID of the account from which the privileged commands will be deleted.
Id String The ID of the command rule that will be deleted.
Note: Make sure there are no spaces in the URL.
HTTP
Method:
DELETE
Header Input:
The following input parameter is required in the header:Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
TheDelete
syntax has these parts:Parameter Type Description Valid
Values
Account PolicyId
text The Policy Id of the account, provided in the URL.
Account Address
text The address of the account, provided in the URL.
Not empty Account
UserName
text The username of the account, provided in the URL.
Not empty Id number The ID of the rule, provided in the
URL.
Not empty
Result:
Status Code: 204 (empty content)Applications
List Applications
Description:
This method returns a list of all the applications in the Vault. The user who runs this web service requires the following permission in the Vault:Audit Users
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Applications/Note: Make sure there are no spaces in the URL.
HTTP Method:
GETHeader
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Query Parameters:
The following parameters can be specified in the URL to filter the result:Parameter Type Description Valid
Values
AppID String Application name.
Not empty Location String Location of
the application in the Vault hierarchy. Default=\ Location
IncludeSublocations Boolean Whether or not the search will be performed in sublocations of the specified location. Default=true true/false For example: /PasswordVault/WebServices/PIMServices.svc/Applications? Location=%5CApplications&AppID=App-1
Result:
{ "application": [ { “AccessPermittedFrom” : <string>, “AccessPermittedTo” : <string>, "AllowExtendedAuthenticationRestrictions": <bool>, “AppID": <string>, “BusinessOwnerEmail” : “<string>”, “BusinessOwnerFName” : “<string>”, “BusinessOwnerLName” : “<string>”, “BusinessOwnerPhone” : “<string>”, “Description”: “<string>”, “Disabled” : <bool>, “ExpirationDate” : <string>, “Location”: “<string>” }] } Status Code: 200List a Specific Application
Description:
This method returns information about a specific application.The user who runs this web service requires the following permission in the Vault:
Audit Users
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Applications/{AppID}The following information is required to replace {AppID}:
Parameter Type Description
AppID String The name of the application about which information is returned.
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.Note: Make sure there are no spaces in the URL.
HTTP
Method:
GET
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
{ }Result:
{ "application": [ { “AccessPermittedFrom” : <string>, “AccessPermittedTo” : <string>, "AllowExtendedAuthenticationRestrictions": <bool>, “AppID": “<string>”, “BusinessOwnerEmail” : “<string>”, “BusinessOwnerFName” : “<string>”, “BusinessOwnerLName” : “<string>”, “BusinessOwnerPhone” : “<string>”, “Description”: “<string>”, “Disabled” : <bool>, “ExpirationDate” : <mm/dd/yyyy>, “Location”: “<string>” } ] } Status Code: 200Add Application
Description:
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:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Applications/Note: Make sure there are no spaces in the URL.
HTTP
Method:
POST
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
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 >", "BusinessOwnerPhone":"<business owner phone>", }
}
The
Add
syntax has these parts:Parameter Type Description Valid
Values
AppID String Application name. Notes:
Specify fewer than 128 characters.
Do not include ampersand (“&”). Application names can include @, but a search for applications cannot include this character.
[class=TableTextBullet] This parameter is required.
Not empty
Description String Description of the application.
Note: Specify up to 29
characters.
Location String Location of the application in the Vault hierarchy.
Note: To insert a
backslash in the location path, use a double backslash. AccessPermitted
From
Integer The hour that access is permitted to the application
Parameter Type Description Valid Values
AccessPermitted To
Integer The hour that access is permitted to the application.
0-23
ExpirationDate String The date when the application expires.
mm-dd-yyyy Disabled Boolean Whether the application is
disabled. Default=false
true/false
BusinessOwner FName
String The first name of the business owner.
Note: Specifies up to 29
characters. BusinessOwner
LName
String The last name of the business owner. BusinessOwner
String The email of the business owner
BusinessOwner Phone
String The phone number of the business owner. Note: Specifies up to 24 characters. Business Owner Phone
Result:
{ } Status Code: 201Description: Application added successfully.
List all Authentication Methods of a Specific Application
Description:
This method returns information about all the authentications methods of a specific application.The user who runs this web service requires the following permission in the Vault:
Audit Users
URL:
http://<IIS_Server_Ip>/PasswordVault/WebServices/ PIMServices.svc/Applications/{AppID}/Authentications The following information is required to replace {AppID}:Parameter Type Description
AppID String The name of the application for which information about the authentication methods are returned.
Note: Make sure there are no spaces in the URL.
HTTP
Method:
GET
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
{ }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>”, }
] }
Add Authentication
Description:
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:
http://<IIS_Server_Ip>/PasswordVault /WebServices/ PIMServices.svc/Applications/{AppID}/Authentications/ The following information is required to replace {AppID}:Parameter Type Description
AppID String The name of the application for which the user is adding a new authentication method.
Note: Make sure there are no spaces in the URL.
HTTP
Method:
POST
Header
Input:
The following input parameter is required in the header:
Parameter Type Description Valid Values
Authorization String The token that identifies the session.
A session token that was returned from the “Logon” method.
Parameters:
The web service parameters depend on the type of authentication specified in the URL.For
Path authentication
: {"authentication":{ “AuthType” : path,
“AuthValue” : “<Path string>”, “IsFolder” : < true/false >,
"AllowInternalScripts":<true/false> }
}
The
Path authentication
syntax has these parts:Parameter Type Description Valid Values
AuthType String The type of authentication. This parameter is required. machineAddress /osUser/path/ hashValue
AuthValue String The content of the
authentication. This parameter is required. IsFolder Boolean Relevant for
Path
authentication only.
Default=false
true/false
AllowInternalScripts Boolean Relevant for Path
authentication only.
Default=false
For
Hash authentication
: {"authentication":{ “AuthType” : hash,
“AuthValue” : “<Hash string>”, "Comment":"<Comment>", }
}
The
Hash authentication
syntax has these parts:Parameter Type Description Valid Values
AuthType String The type of authentication. This parameter is required. machineAddress/osUser/path/ hashValue
AuthValue String The content of the
authentication. This
parameter is required. Comment String Relevant for
Hash
authentication only.
Text
For
OS user authentication
: {"authentication":{ “AuthType” : osUser,
“AuthValue” : “<OS User Name>” }
}
The
OS user authentication
syntax has these parts:Parameter Type Description Valid Values
AuthType String The type of authentication. This parameter is required. machineAddress/osUser/path/ hashValue
Parameter Type Description Valid Values
AuthValue String The content of the
authentication. This
parameter is required.
For
Address authentication
: {"authentication":{
“AuthType” : machineAddress, “AuthValue” : “<machine address>”
} }
The
Address authentication
syntax has these parts:Parameter Type Description Valid Values
AuthType String The type of authentication. This parameter is required. machineAddress/osUser/path/ hashValue
AuthValue String The content of the authentication. This parameter is required.
