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:

  1. To GET the resources owned and shared to a user
  2. To GET the accounts that are part of a resource
  3. To GET details of an account
  4. To GET the password of an account that is part of a resource
  5. To change the password of an account
  6. To create a new resource
  7. To GET the ID of an account of a resource

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>:<Port>/restapi/json/v1/<Method Name>?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.


{
 "operation":{
  "name":"GET RESOURCES",
  "result":{
   "status":"Success",
   "message":"Resources fetched successfully"
  },
  "totalRows":3,
  "Details":[
   {
    "RESOURCE DESCRIPTION":"CentOS Machine",
    "RESOURCE NAME":"CentOS Machine",
    "RESOURCE ID":"301",
    "RESOURCE TYPE":"Linux",
    "NOOFACCOUNTS":"3"
   },
   {
    "RESOURCE DESCRIPTION":"Cisco IOS Device",
    "RESOURCE NAME":"Cisco IOS Device",
    "RESOURCE ID":"302",
    "RESOURCE TYPE":"Cisco IOS",
    "NOOFACCOUNTS":"2"
   },
   {
    "RESOURCE DESCRIPTION":"Weblogic Data Source Password",
    "RESOURCE NAME":"MSSQL Server",
    "RESOURCE ID":"303",
    "RESOURCE TYPE":"MS SQL Server",
    "NOOFACCOUNTS":"2"
   }
  ]
 }
}


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 Request

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

Sample Output

{
 "operation":{
  "name":"GET RESOURCE ACCOUNTLIST",
  "result":{
   "status":"Success",
   "message":"Resource details with account list fetched successfully"
  },
  "Details":{
   "RESOURCE ID":"303",
   "RESOURCE NAME":"MSSQL Server",
   "RESOURCE DESCRIPTION":"Weblogic Data Source Password",
   "RESOURCE TYPE":"MS SQL Server",
   "DNS NAME":"sqlserver-1",
   "PASSWORD POLICY":"Strong",
   "DEPARTMENT":"SQL Server DBA",
   "LOCATION":"Level 10",
   "RESOURCE URL":"http://sqlserver-1/",
   "RESOURCE OWNER":"admin",
   "CUSTOM FIELD":[
    {
     "CUSTOMFIELDVALUE":"78736298",
     "CUSTOMFIELDTYPE":"Numeric",
     "CUSTOMFIELDLABEL":"License No",
     "CUSTOMFIELDCOLUMNNAME":"COLUMN_LONG1"
    },
    {
     "CUSTOMFIELDVALUE":"Sep 10, 2014",
     "CUSTOMFIELDTYPE":"Date",
     "CUSTOMFIELDLABEL":"Installed Date",
     "CUSTOMFIELDCOLUMNNAME":"COLUMN_DATE1"
    },
    {
     "CUSTOMFIELDVALUE":"Test123$%^%",
     "CUSTOMFIELDTYPE":"Password",
     "CUSTOMFIELDLABEL":"Resource Password",
     "CUSTOMFIELDCOLUMNNAME":"COLUMN_SCHAR1"
    },
    {
     "CUSTOMFIELDVALUE":"YES",
     "CUSTOMFIELDTYPE":"Character",
     "CUSTOMFIELDLABEL":"Secure Resource",
     "CUSTOMFIELDCOLUMNNAME":"COLUMN_CHAR1"
    }
   ],
   "ACCOUNT LIST":[
    {
     "ISFAVPASS":"false",
     "ACCOUNT NAME":"sysdba",
     "PASSWDID":"308",
     "PASSWORD STATUS":"[In Use]",
     "ACCOUNT ID":"308"
    },
    {
     "ISFAVPASS":"false",
     "ACCOUNT NAME":"system",
     "PASSWDID":"307",
     "PASSWORD STATUS":"****",
     "ACCOUNT ID":"307"
    }
   ]
  }
 }
}

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

{
 "operation":{
  "name":"GET RESOURCE ACCOUNT DETAILS",
  "result":{
   "status":"Success",
   "message":"Account details fetched successfully"
  },
  "Details":{
   "DESCRIPTION":"",
   "LAST ACCESSED TIME":"N/A",
   "LAST MODIFIED TIME":"Sep 10, 2014 03:33 PM",
   "PASSWORD STATUS":"****",
   "PASSWDID":"307",
   "CUSTOM FIELD":[
    {
     "CUSTOMFIELDVALUE":"5645567",
     "CUSTOMFIELDTYPE":"Numeric",
     "CUSTOMFIELDLABEL":"Account Lic Number",
     "CUSTOMFIELDCOLUMNNAME":"COLUMN_LONG1"
    },
    {
     "CUSTOMFIELDVALUE":"Sep 10, 2014",
     "CUSTOMFIELDTYPE":"Date",
     "CUSTOMFIELDLABEL":"Acc Creation Date",
     "CUSTOMFIELDCOLUMNNAME":"COLUMN_DATE1"
    },
    {
     "CUSTOMFIELDVALUE":"Test12345",
     "CUSTOMFIELDTYPE":"Password",
     "CUSTOMFIELDLABEL":"Secondary Password",
     "CUSTOMFIELDCOLUMNNAME":"COLUMN_SCHAR1"
    },
    {
     "CUSTOMFIELDVALUE":"YES",
     "CUSTOMFIELDTYPE":"Character",
     "CUSTOMFIELDLABEL":"Secure Account",
     "CUSTOMFIELDCOLUMNNAME":"COLUMN_CHAR1"
    }
   ]
  }
 }
}


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 Request

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

{
 "operation":{
"name":"GET PASSWORD",
  "result":{
   "status":"Success",
   "message":"Password fetched successfully"
  },
  "Details":{
   "PASSWORD":"fqxdB7^)4"
  }
 }
}

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 Request

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.

Sample Input Data

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 Request

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 Request

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"
  }
 }
}

© 2014, ZOHO Corp. All Rights Reserved.