RESTful API (Feature available only in the Enterprise Edition)
87 minutes to read
Introduction
Password Manager Pro APIs allow you to connect, interact and integrate with Password Manager Pro
directly. The APIs belong to the REpresentational State Transfer (REST) category. Password Manager Pro APIs use the GET, PUT, and POST methods to offer a wide range of operations such as creating resources and adding accounts to them, adding SSL certificates and SSH keys, associating SSH keys with resources, retrieving passwords, retrieving resource/account details, updating passwords programmatically, sharing resources/accounts to users and so on.
Pre-requisite
Creating API user accounts is the first step in the process of configuring REST APIs for Application-to-Application
password management. Click here to know how to create an API user account.
APIs Summary
Methods used to invoke APIs
GET
To fetch resources, accounts, passwords, account/resource details
PUT
To change a password
POST
To create new resource and accounts
How to make use of the APIs?
Invoking the APIs
The APIs can be invoked via HTTP POST, GET and PUT requests. All parameters in the request should be
form-urlencoded. For all the APIs you need to pass the AUTH token, which is mandatory.
Supported Format
Password Manager Pro supports the JSON format and the URL structure for it is given below:
In case the setting at your end demands a reason to be supplied for retrieving a password, you
need to pass the following details as input. If the ticketing system is enabled, you need
to pass ticket ID for validation.
INPUT_DATA={"operation":{"Details":{"REASON":"Need the password to Login Windows Server","TICKETID":"7"}}}
curl -X GET -k -H "Content-Type: text/json" -H "AUTHTOKEN:<<Authtoken_generated_from_Password_Manager_Pro>>" https://<Host-Name-of-Password-Manager-Pro-Server-OR-IP-Address>:<Port>/restapi/json/v1/resources/2/accounts/2/password --data-urlencode INPUT_DATA={"operation":{"Details":{"REASON":"Need the password to Login Windows Server"}}}
Note: If there occurs any problem on retrieving password, the reason will be displayed
as part of message.
5. Change the Password of an Account
Description
To change the password of an account that is part of a resource, you need to pass both Resource
ID and Account ID to fetch the required details. If the ticketing system is enabled, you
need to pass ticket ID for validation.
Note: If there occurs any problem on changing password, the reason will be displayed
as part of message.
6. Create a New Resource
Description
To create a new resource in Password Manager Pro.
Input Data
You need to pass input data such as name of the resource, account name, resource type, password,
URL, description, notes and any other additional fields at the resource and account levels.
You can add as many as 40 custom fields (20 each at resource and account levels). Of these,
resource name, account name, resource type and password are mandatory.
{
"operation":{
"name":"CREATE RESOURCE",
"result":{
"status":"Success",
"message":"Resource Windows Server has been added successfully"
}
}
Note: If you want to add a new resource under Administrator/Password Administrator/Privileged
Administrator an additional parameter "OWNERNAME" having the value of that particular
user should be added to the resource details. While adding the resource to AD user, the
username must be in the format "Domain-Name\\UserName".
Note: If you want to add a resource to a static resource group, an additional
parameter "RESOURCEGROUPNAME" having the value of that particular resource group should
be added to the resource creation input. If the group already exists, this resource will
be added to that group; otherwise, a new group with the name specified here will be created.
Note: You can also add files as a separate resource in Password Manager Pro. To
add a file as a new resource, the 'Content-Type' in the request has to be modified as
shown in the sample below. Once you have modified, you just have to pass the file along
with it.
{
"operation":{
"name":"GET_RESOURCEACCOUNTID",
"result":{
"status":"Success",
"message":"Resource ID and account ID fetched successfully for the given resource
name and account name."
},
"Details":{
"RESOURCEID":"303",
"ACCOUNTID":"307"
}
}
}
8. Get the Resource ID using the Resource Name
Description
To fetch the resource ID, you can provide the resource name alone in the URL.
Note: Requester ID is the same as the ID of the user who has requested the password. REQUESTEDID
can be obtained from the GET PASSWORDREQUEST API(REQUESTER USERID).
Sample Request
curl -X POST -k -H "AUTHTOKEN:<<Authtoken_generated_from_Password_Manager_Pro>>" -H "Content-Type: text/json" https://<Host-Name-of-Password-Manager-Pro-Server-OR-IP-Address>:<Port>/restapi/json/v1/accounts/7/requester/34/approve
Note: If you want to edit resource type, an additional parameter "RESOURCETYPE"
having the value of that particular resource type should be added to the input. While
editing 'Resource Type' cannot be changed from Key Store, File Store, License Store,
Rackspace, and AWS IAM to other resource types and viceversa.
In case the setting at your end demands a reason to be supplied for downloading the file, you
need to pass the following details as input. If the ticketing system is enabled, you need
to pass ticket ID for validation.
INPUT_DATA={"operation":{
"Details":{
"REASON":"Need the key file to connect the remote host", //optional when reason is forced
"TICKETID":"7", // optional when ticketing system is enabled
"ISCUSTOMFIELD":"true" //optional Need to be given if the file to be downloaded is account/resource additional field file type
"CUSTOMFIELDTYPE":"ACCOUNT / RESOURCE" // optional -If its account additional field it must be ACCOUNT or if its resource
additional field it must be RESOURCE
"CUSTOMFIELDLABEL" : "LicenseFIle" // optional - Name of the resource/account additional field
}
}
}
You need to pass input data such as account list, name of the accounts, passwords, and description.
The params RECORD_RDP_SESSIONS, RECORD_CLI_SESSIONS, DISABLE_PASSWORD_RESETS, CONFIGURE_PASSWORD_RESET, ACCOUNT_RESOURCE_GROUP_IDS, IIS_WEB_CONFIG_RESET, IIS_APP_POOL_RESTART, IIS_APP_POOL_RESET, SERVICES_RESTART, SERVICES_RESET and SCHEDULED_TASK_RESET are available from build 12230 and above only.
The params TOTP_SECRET, TOTP_ALGORITHM, TOTP_DIGITS, and TOTP_VALIDITY are available from build 12430 and above only.
You need to pass the TOTP_SECRET param in the input data to configure TOTP for an account. By default, the website accounts configured with TOTP as the 2FA supports the SHA1 Algorithm, 6-digit TOTP codes, and a validity of 30 seconds. If your account supports a different set of parameters for TOTP codes, use these params TOTP_ALGORITHM, TOTP_DIGITS, and TOTP_VALIDITY.
The params RECORD_RDP_SESSIONS, RECORD_CLI_SESSIONS, DISABLE_PASSWORD_RESETS, CONFIGURE_PASSWORD_RESET, ACCOUNT_RESOURCE_GROUP_IDS, IIS_WEB_CONFIG_RESET, IIS_APP_POOL_RESTART, IIS_APP_POOL_RESET, SERVICES_RESTART, SERVICES_RESET and SCHEDULED_TASK_RESET are available from build 12230 and above only.
The params TOTP_SECRET, TOTP_ALGORITHM, TOTP_DIGITS, and TOTP_VALIDITY are available from build 12430 and above only.
To reconfigure the TOTP for an account, the TOTP_SECRET param should be passed in the input data along with the ACCOUNTNAME param, whereas to remove the TOTP for an account, the TOTP_SECRET param value should be empty.
Note: Including the Input Data in the API request is optional. In case input data is provided, you can add any one or all of the available filters: withExpiryDaysLessThan,withKeyLength,withSignatureAlgorithm.
{ "name": "Get SSL Discovery", "totalRows": 4, "details": { "192.168.216.1": [ "FAILURE", "Connection failed,no certificate found at port 443" ], "192.168.216.0": [ "FAILURE", "Connection timed out,no certificate found at port 443" ], "192.168.216.2": [ "FAILURE", "Connection timed out,no certificate found at port 443" ], "192.168.216.3": [ "FAILURE", "Connection timed out,no certificate found at port 443" ] } }
{
"operation": {
"name":"get_USERID",
"result": { "status":"Success","message":"User Id for the specified username have been
fetched successfully"},"Details":{"USERID":"1"}}}
{"operation":{"name":"GET_USERGROUPID","result":{"status":"Success","message":"Usergroup Id for the specified usergroup name have been fetched successfully. "},"Details":{"USERGROUPID":"1"}}}
65. Configure Remote Password Reset for Linux Resources
(API applicable from build 11200 and above only)
Description
To configure remote password reset for Linux resources
Note: It is optional to provide the server name. The server name allows you to deploy certificates to that particular server. Without the server name, the certificates are deployed to all the saved servers from the client.
INPUT_DATA={"operation":{"Details":{ "group_name":"NAME","group_description":"This is the description for the group certificate","group_mail":"pmp@zohocorporation.com","ssl_details":"301,202"}}}
Sample Response
{"result":{"message":"Certificate group added successfully.","status":"Success"},"name":"createCertificateGroup"}
76. Delete SSL Certificate Group (API applicable from build 11300 and above only)
INPUT_DATA={"operation":{"Details":{ "group_name":"NEW NAME","group_description":"This is new description for the group certificate","group_mail":"pmp1@zohocorporation.com","ssl_details":"1,2,3"}}}
Sample Response
{"result":{"message":"The certificate group is updated successfully.","status":"Success"},"name":"editCertificateGroup"}
78. Generate an SSL Agent Install Key (API applicable from build 11300 and above only)
{ "operation":{ "name":"GET RESOURCE GROUP ID","result": { "status":"Success","message":"Resource Group Id for the specified Resource Group name have been fetched successfully."} ,"Details":{"RESOURCEGROUPID":"1" }}}
86. Reset Two-Factor Authentication (API applicable from build 12100 and above only)
Description
To reset two-factor authentication for a username.
INPUT_DATA={
"operation":{
"details":{
"password": "Test@123",
// Either Password Policy or Password Policy ID should be given
"passwordPolicy": "Strong",
"passwordPolicyId":"1"
}
}
}
Provide INPUT_DATA only for generating a new agent key.
Sample Input
INPUT_DATA={
"operation": {
"details": {
"generateAgentKey": "true",
"validityPeriod":3 // Provide this param to use the agent key in multiple installations for a stipulated time (In hours).
}
}
}