RESTful API

PMP APIs allow any application to connect, interact and integrate with Password Manager Pro directly. The APIs belong to the REpresentational State Transfer (REST) category and allow you to add resources, accounts, retrieve passwords, retrieve resource/account details and update passwords programmatically.

Prerequisites

Create API User Accounts in PMP

This is the first step in the process to configure and use Password Management APIs for Application-to-Application Password Management. As mentioned above, user accounts have to be created in PMP to those who will use only the Password Management API. Every API user account should be attached to a single endpoint (server or desktop from where the API is used, so the user accounts are uniquely identified – for example, as user@hostname)

To create an API user account

    1. Click "Add API User" button in "Admin >> Users" tab
    2. In the "Add API User" UI that opens up, enter the 'User Name' in the respective text field.
    3. Enter the name of the host from where the API user would access PMP for password management operations.
    4. 'Full Name' refers to the name with which the API user would be identified in the external world. That means, in reports, audit trails and such other places where activities are traced to users.
    5. Select an appropriate access level for the API user being added - Administrator/Password Administrator/Password User
    6. If you are adding a user as "Administrator" or "Password Administrator", you can specify the 'Access Scope'. If you select the option, "Passwords Owned and Shared", the administrator/password administrator will be able to view the passwords owned by them and those shared to them by others. You can choose to make the administrator/password administrator a super administrator, you need to select the option "All Passwords in the System". When you do so, the administrator or the password administrator will be able to access all passwords in PMP without any restriction.
    7. Leave the options "Public key for SSH CLI access" and "SSL Certificate for XML-RPC API access"
    8. Enable REST API by clicking the button "Enable" beside REST API
    9. Once you do this, you will see a text box for the API key. Click "Generate" to generate the API key. The API key is the Auth Token for your access purposes. Copy down this key and store it in some secure location for your future reference. This key will be displayed in the GUI only once and it will not be shown. If you ever lose this key, you need to come back to this GUI and regenerate the key.
    10. You can set validity period for the API key - you can choose the option "Never Expires" if you want the key to be valid for ever. Otherwise, specify a validity date.

Important Note

The API User creation is specific to the host from where the application would contact PMP for passwords. That means, user and host are tied with other. If you want to make use of Password Management API from more than one host, you need to create as many API users as the number of hosts. Conversely, if you wish to have many users on a single host, then again you need to create as many API users as needed.

APIs summary

PMP provides a total of seven 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 via HTTP POST, GET and PUT requests. All parameters in the request should be form-urlencoded. For all the APIs you need to pass AUTH token, which is mandatory.

Supported Format

PMP supports JSON format and the URL structure for would be as below:

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/resources/<Resource ID>/accounts/<Account ID>?AUTHTOKEN=(The token you have generated and copied from the GUI)

1.To GET the resources owned and shared to a user

Description:

Used to get the list of resources which are owned/shared to an API user

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json /v1/resources?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

GET

Input Data:

None

Sample Requests

curl -k https://192.168.xx.xx:7272/restapi/json/v1/resources?AUTHTOKEN=B9A1809A-5BF7-4459-9ED2-8D4F499CB902

Sample Output

In the output (as shown in the sample below), you will get all the resources owned and shared by the specific API user.


2.To GET the accounts that are part of a resource

Description

To get the list of accounts and resource details present in the resource. Resource ID can be obtained from the GET RESOURCES API (explained above).

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json /v1/resources/<Resource ID>/accounts?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

GET

Input Data:

None

Sample Requests

curl -k https://192.168.xx.xx:7272/restapi/json/v1/resources/303/accounts?AUTHTOKEN=B9A1809A-5BF7-4459-9ED2-8D4F499CB902

Sample Output

In the output (as shown in the sample below), you will get all the resources owned and shared by the specific API user.


Note: If password access control had been enabled AND If the password status is 'IN USE', you will see the output as [ In use ].


3.To GET details of an account

Description

To get the details of an account that is part of a resource. You need to pass both Resource ID and Account ID to fetch the required details.

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/resources/<Resource ID>/accounts/<Account ID>?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

GET

Input Data:

None

Sample Requests

curl -k https://192.168.xx.xx:7272/restapi/json/v1/resources/303/accounts/307?AUTHTOKEN=B9A1809A-5BF7-4459-9ED2-8D4F499CB902

Sample Output


4.To GET the password of an account that is part of a resource

Description

To get 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.

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/resources/<Resource ID>/accounts/<Account ID>/password?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

GET

Input Data:

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

INPUT_DATA={"operation":{"Details":{"REASON":"Need the password to Login Windows Server"}}}

Sample Requests

curl -k https://192.168.xx.xx:7272/restapi/json/v1/resources/303/accounts/307/password?AUTHTOKEN=B9A1809A-5BF7-4459-9ED2-8D4F499CB902


curl -X GET -k -H "Content-Type: text/json" --url 'https://192.168.xx.xx:7272/restapi/json/v1/resources/303/accounts/307/password?AUTHTOKEN=B9A1809A-5BF7-4459-9ED2-8D4F499CB902&INPUT_DATA=\{"operation":\{"Details":\{"REASON":"Need the password to Login Windows Server"\}\}\}'

Sample Output


Note :If there occurs any problem on retrieving password, the reason will be displayed as part of message.


5.To 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.

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/resources/<Resource ID>/accounts/<Account ID>/password?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

PUT

Input Data:

You need to pass input data such as new password, reset type and reason. Reset type should be either LOCAL or REMOTE.

        INPUT_DATA={
   "operation":{
      "Details":{
         "NEWPASSWORD":"Test@12345$",
         "RESETTYPE":"LOCAL",
         "REASON":"Password Expired"
      }
   }
}
        

Sample Requests

curl -X PUT -k -H "Content-Type: text/json" --url https://192.168.xx.xx:7272/restapi/json/v1/resources/303/accounts/307/password?AUTHTOKEN=B9A1809A-5BF7-4459-9ED2-8D4F499CB902 -d INPUT_DATA=\{operation:\{Details:\{NEWPASSWORD:Test12345$,RESETTYPE:LOCAL,REASON:test\}\}\}

Sample Output

{
 "operation":{
  "name":"CHANGE PASSWORD",
  "result":{
   "status":"Success",
   "message":"Password changed successfully"
  }
 }
}

Note :If there occurs any problem on changing password, the reason will be displayed as part of message.


6.To create a new resource

Description

To create a new resource in PMP

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.

        INPUT_DATA={
   "operation":{
      "Details":{
         "RESOURCENAME":"Windows Server",
         "ACCOUNTNAME":"Administrator",
         "RESOURCETYPE":"Windows",
         "PASSWORD":"Test123#@!",
         "NOTES":"Testing API",
         "RESOURCEURL":"http://windowsserver/adminconsole",
         "RESOURCECUSTOMFIELD":[
            {
               "CUSTOMLABEL":"Secure Resource",
               "CUSTOMVALUE":"YES"
            }
         ]
      }
   }
}
        

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/resources?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

POST

Sample Requests

curl -X POST -k -H "Content-Type: text/json" 
'https://192.168.39.29:7272/restapi/json/v1/resources?AUTHTOKEN=B9A1809A-5BF
7-4459-9ED2-8D4F499CB902' -d 
'INPUT_DATA={"operation":{"Details":{"RESOURCENAME":"Windows 
Server","ACCOUNTNAME":"Administrator","RESOURCETYPE":"Windows","PASSWORD"
:"Test123#@!","NOTES":"Testing 
API","RESOURCEURL":"http://windowsserver/adminconsole","RESOURCECUSTOMFIEL
D":[{"CUSTOMLABEL":"Secure Resource","CUSTOMVALUE":"YES"}]}}}' 

Sample Output

{
 "operation":{
  "name":"CREATE RESOURCE",
  "result":{
   "status":"Success",
   "message":"Resource Windows Server has been added successfully"
  }
 }

7.To GET the ID of an account of a resource

Description

To get the ID of an account of a resource in PMP. You need to pass the name of the resource and account in the URL/

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/resources/resourcename/<Resource Name>/accounts/accountname/<Account Name>?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

GET

Input Data:

None

Sample Requests

curl -k https://192.168.xx.xx:7272/restapi/json/v1/resources/resourcename/MSSQLServer/a ccounts/accountname/system?AUTHTOKEN=B9A1809A-5BF7-4459-9ED2-8D4F499CB902

Sample Output

{
 "operation":{
  "name":"GET_RESOURCEACCOUNTNAME",
  "result":{
   "status":"Success",
   "message":"Resource id and account id fetched successfully for the given resource
name"
  },
  "Details":{
   "RESOURCEID":"303",
   "ACCOUNTID":"307"
  }
 }
}


8.To DELETE a Resource in PMP:

Description

To delete a resource for the given resource ID. Resource ID can be obtained from the GET RESOURCES API (explained above).

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/resources/{resourceid}?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

DELETE

Input Data :

None

Sample Requests

curl -X POST -k -H "Content-Type: text/json" https://192.168.xx.xx:7272/restapi/json/v1/resources/307?AUTHTOKEN=iddPyMeUOnv9huR%2BzLfan1GbB4VYZ4%2F7UDHfbpY8socCJ7C1%2BVUyhjtcRHlysShHeLf9va63EEkt%0A4x%2FG42EYLQ%3D%3D

Sample Output


{
"operation":{
"name":"DELETE RESOURCE"
"result":{"status":"Success"
"message":"Resources deleted successfully."}
}
}

9.To GET the list of Password Requests

Description

Method to get the list of password requests to be approved/rejected by the admin logged in.

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/accounts/passwordaccessrequests?AUTHTOKEN=(The token you have generated and copied from the GUI)


HTTP METHOD:

GET

Input Data :

None


Sample Requests

curl -k https://192.168.xx.xx:7272/restapi/json/v1/accounts/passwordaccessrequests?AUTHTOKEN=iddPyMeUOnv9huR%2BzLfan1GbB4VYZ4%2F7UDHfbpY8socCJ7C1%2BVUyhjtcRHlysShHeLf9va63EEkt%0A4x%2FG42EYLQ%3D%3D

Sample Output

{
"operation":{
               "name":"GET_PASSWORDREQUEST"

               "result":{   
                          "status"    :   "Success"  
                          "message" : "Password Request fetched successfully"
                        }

                "Details":{  
                            "REQUESTER USERID"  :  "2"
                            "REQUESTED BY" : "guest"
                            "REQUESTED BY FULLNAME" : "Guest guest"
                            "PASSWORDREQUESTLIST" : [

                                {
                                  "ACCOUNT ID"  :  "1"
                                  "ACCOUNT NAME" :  "ACCOUNT1"
                                  "RESOURCE ID":"1"
                                  "RESOURCE NAME":"apt-server1"
                                  "PASSWD ID" : "1"
                                  "STATUS":""
                                  "REQUESTED TIME":"Nov 27
                                  "REASON" : "For connecting the machine and update the pmp server".
                                }

                                         {
                                           "ACCOUNT ID"  :  "2"
                                           "ACCOUNT NAME" :  "ACCOUNT2"
                                           "RESOURCE ID":"2"
                                           "RESOURCE NAME":"apt-server2"
                                           "PASSWD ID" : "2"
                                           "STATUS":""
                                           "REQUESTED TIME":"Nov 28
                                           "REASON" : "For connecting the machine and update the pmp server".
                                         }

                                  ]      
    
                           }

                 }

}

10.To Request Password Approval by the Admin:

Description

Method to request the admin for password access approval. The account id has to be passed for the same in the URL.

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/accounts/{accountid}/requestpassword?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

POST

Input Data:

In case the setting at your end demands a reason to be supplied for requesting a password, you need to pass the following details as input.

Sample Input

INPUT_DATA= { "operation" : { "Details" : { "REASON" : "asdefefe"}}}

Sample Requests

curl -X POST -k -H "Content-Type: text/json" https://192.168.xx.xx:7272/restapi/json/v1/accounts/7/requestpassword?INPUT_DATA= { "operation" : { "Details" : { "REASON" : "Testing"}}}&AUTHTOKEN=iddPyMeUOnv9huR%2BzLfan1GbB4VYZ4%2F7UDHfbpY8socCJ7C1%2BVUyhjtcRHlysShHeLf9va63EEkt%0A4x%2FG42EYLQ%3D%3D

Sample Output


{
"operation":{

               "name":"REQUEST_PASSWORD"  ,

               "result":{    
                          "status": "Success"    ,
                          "message":"Request to view password have been raised successfully"
                         },
               
               "Details":{
                           "STATUS" : "WAITING FOR APPROVAL / CHECKOUT" ;
                          }

            }

}

11.To Reject a Password Request

Description

Method for the admin to reject the password requests. This requires the account ID and requester ID to be passed in the URL.

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/accounts/{accountid}/requester/{requesterid}/reject?AUTHTOKEN=(Theoken you have generated and copied from the GUI)

HTTP METHOD:

POST

Input Data :

None

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 Requests

curl -X POST -k -H "Content-Type: text/json" https://192.168.xx.xx:7272/restapi/json/v1/accounts/7/requester/34/reject?AUTHTOKEN=iddPyMeUOnv9huR%2BzLfan1GbB4VYZ4%2F7UDHfbpY8socCJ7C1%2BVUyhjtcRHlysShHeLf9va63EEkt%0A4x%2FG42EYLQ%3D%3D

Sample Output


{
"operation":{
               "name" : "ADMIN_REQUEST_REJECT" 
               "result" : { 
   
                            "status"    :     "Success"   
                            "message" : "Password Rejected successfully"
                           }
              
            }

}

12.To Approve a Password Request

Description

Method for the admin to approve the password requests. Here, the account ID and the Requester ID are required to be passed in the URL.

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/accounts/{accountid}/requester/{requesterid}/approve?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

POST

Input Data :

None

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 Requests

curl -X POST -k -H "Content-Type: text/json" https://192.168.xx.xx:7272/restapi/json/v1/accounts/7/requester/34/approve?AUTHTOKEN=iddPyMeUOnv9huR%2BzLfan1GbB4VYZ4%2F7UDHfbpY8socCJ7C1%2BVUyhjtcRHlysShHeLf9va63EEkt%0A4x%2FG42EYLQ%3D%3D

Sample Output


{
"operation" : { 

               "name" : "ADMIN_REQUEST_APPROVE" 

               "result" : {    
                           "status"    :     "Success"   
                           "message" : "Password Approved successfully"
                           }

               }

}

13.To Check-in Password Approved by Admin

Description

Method to check-in the password approved by the admin. The account and requester IDs have to passed in the URL for the same.

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/accounts/{accountid}/requester/{requesterid}/checkin?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

POST

Input Data :

None

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 Requests

curl -X POST -k -H "Content-Type: text/json" https://192.168.xx.xx:7272/restapi/json/v1/accounts/7/requester/34/checkin?AUTHTOKEN=iddPyMeUOnv9huR%2BzLfan1GbB4VYZ4%2F7UDHfbpY8socCJ7C1%2BVUyhjtcRHlysShHeLf9va63EEkt%0A4x%2FG42EYLQ%3D%3D

Sample Output


{
  "operation" : {

                  "name" : "ADMIN_REQUEST_CHECKIN" 

                  "result" : {    
                          	  "status"    :     "Success"   
                         		"message" : "Password have been checked in successfully"
                              }

                  }

}

14.To Checkout the Password approved by the Admin

Description

Method to checkout the password after being approved by the admin after request. The account ID had to be passed for the same in the URL.

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/accounts/{accountid}/checkout?AUTHTOKEN=<token>&INPUT_DATA=<json>

HTTP METHOD:

POST

Input Data

On account of customized settings that demand reason for password checkout, you need to pass the following as input.

Sample Input

{
"operation"    :    {
               "Details":   {
                                 "REASON":"N/A"
                            }
             }
}

Sample Requests

curl -X POST -k -H "Content-Type: text/json" https://192.168.xx.xx:7272/restapi/json/v1/accounts/7/checkout?INPUT_DATA= { "operation" : { "Details" : { "REASON" : "N/A"}}}&AUTHTOKEN=iddPyMeUOnv9huR%2BzLfan1GbB4VYZ4%2F7UDHfbpY8socCJ7C1%2BVUyhjtcRHlysShHeLf9va63EEkt%0A4x%2FG42EYLQ%3D%3D

Sample Output

{
"operation" : {
                "name" : "REQUEST_CHECKOUT"

                "result" : {   
                    		   "status" : "Success"  
		                       "message" : "Password have been checked out successfully"
                            }

                 "Details":  
    
             		       {
                   			 "STATUS" : "***** [checkIn]"
                        	}
                }

}

15.To Check-in password by the requested user

Description

Method to checkin the password after being approved by the admin after request. The account ID had to be passed for the same in the URL

URL

https://<Host-Name-of-PMP-Server OR IP address>:7272/restapi/json/v1/accounts/{accountid}/checkin?AUTHTOKEN=(The token you have generated and copied from the GUI)

HTTP METHOD:

POST

Input Data :

{
"operation"    :    {
              
               "Details":   {
                                       "REASON":"N/A" // not required for now send reason as N/A .
                                   }
             }
 }
 
 

Sample Requests

curl -X POST -k -H "Content-Type: text/json" https://192.168.xx.xx:7272/restapi/json/v1/accounts/{accountid}/checkin? AUTHTOKENEN=iddPyMeUOnv9huR%2BzLfan1GbB4VYZ4%2F7UDHfbpY8socCJ7C1%2BVUyhjtcRHlysShHeLf9va63EEkt%0A4x%2FG42EYLQ%3D%3D

Sample Output

{
"operation"    :    {
               		"name" : "REQUEST_CHECKIN"  ,

              		"result" : {   
                             
                         			"status":"Success"    ,
                         			"message":"Password have been checked in successfully"
                                          
                                  },
                                   
            		"Details" : {
                             
                               		"STATUS" : "[REQUEST]"

                            	    }
                     }
}

16.To create a new User

Description

Method to add an user

URL

https://severname:port/restapi/json/v1/user?AUTHTOKEN=<token>&INPUT_DATA=<json>

HTTP METHOD:

POST

Input Data (Optional Inputs are given in Grey)

{
    "operation": {
        "Details": {
         "USERNAME": "jason"
         "FIRSTNAME": "Jason"
         "LASTNAME": "Thomas"
         "EMAIL": "jason@opmanager.com"
         "PASSWORD":"Pa55w0Rd123"
         "POLICY": "Strong"
         "ROLE": "Administrator|Password Administrator|Password Auditor|Password User"
         "ISSUPERADMIN": "true|false",
         "DEPARTMENT": "NOC",
         "LOCATION": "Level 10 - South Wing",
         "ENABLEMOBILEACCESS": "true|false",
         "LANDLINE_COUNTRYCODE": "+1",
         "LANDLINE": "925-965-9647",
         "LANDLINE_EXT": "4675",
         "MOBILE_COUNTRYCODE": "+1",
         "MOBILE": "925-965-9648",
         "PHONEFACTOR_USERNAME": "jason1",
         "RSAUSERNAME": "jason2",
         "ENABLETWOFACTOR": "true|false",
         "PRIMARYCONTACT": "landline|mobile"
        }

    }
}

Sample Output

{
	"operation":{"name":"CREATE_USER",
	"result":{"status":"Success",
	"message":"User Created Successfully"
    			  }
    		  }
}

©2014, ZOHO Corp. All Rights Reserved.

Top