Top

RESTful API

Key Manager Plus (KMP) APIs allow other applications to connect, interact and integrate with Key Manager Plus directly. These APIs belong to the REpresentational State Transfer category and allow applications to create, fetch, associate digital keys and add, retrieve or manage users programmatically.

Pre-requisites

Generate API key

The first step to configure and use KMP APIs is generating the API key from the KMP user interface. Only administrator users can generate the API keys. The API keys serve as the auth token for your access purposes. The API keys are tied to the host in which they are created.

To generate API key

APIs Summary

KMP provides a total of twenty-four APIs:

HTTPS methods:

GET

To fetch resources, user accounts, keys, account/resource details

DELETE

To delete an existing key or a certificate

POST

To create new keys, certificates or to discover resources

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-url encoded. For all the APIs you need to pass AUTH token, which is mandatory.

Supported Format

The URL structure for the KMP API would be as below:

https:// <Host-Name-of-KMP-Server OR IP address> :6565/api/pki/restapi/ <api_name> /AUTHTOKEN=(The token you have generated and copied from the GUI)

1.To create a new SSH key

Description:

To create a new SSH key

HTTPS method:

POST

Input data:

The following data to be passed as input

{"operation":{"Details":{"keyName":"keytest",
"passPhrase":"passPhrase",
"comment":"comment",
"length":"2048",
"keyType":"SSH2_RSA"}}}

Sample request

https:// <HostName> :6565/api/pki/restapi/createsshkey?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE&INPUT_DATA={"operation":{"Details":{"keyName":"keytest","passPhrase":"passPhrase","comment":"comment","length":"2048","keyType":"SSH2_RSA"}}}

Sample response:

{ "name": "CreateSSHKey",
"result": {
"status": "Success",
"message": "New SSH key created successfully"v }
}

2.To update credentials

Description:

To update credentials for the discovered resources.

HTTPS method:

POST

Input data:

The following data to be passed as input

{"operation":{"Details":{"userName":"test3",
"password":"test3",
"resourceName":"172.21.147.80",
"isAdmin":"false"}}}

Sample request:

https:// <HostName> :6565/api/pki/restapi/applycredentials?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE&INPUT_DATA={"operation":{"Details":{"userName":"test3","password":"test3","resourceName":"172.21.147.80","isAdmin":"false"}}}

Sample response:

{
"name": "ApplyCredentials",
"result": {
"status": "Success",
"message": "Credentials updated successfully"
}
}

3.To fetch all the SSH keys

Description:

To fetch all the discovered SSH keys

HTTPS method:

GET

Input data:

None

Sample request:

https://<HostName>:6565/api/pki/restapi/getAllSSHKeys?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE

Sample response:

{
"name": "GetAllSSHKeys",
"result": {
"status": "Success",
"message": "All SSH Keys fetched successfully"
},
"totalRows": 2,
"SSHKeys": [
{
"KeyName": "key",
"KeyType": "ssh-rsa",
"KeyLength": "2048",
"FingerPrint": "4b:97:8d:aa:8d:73:89:7c:96:69:7d:10:df:b2:d0:af",
"CreatedBy": "admin",
"CreationTime": "1 days"
},
{
"KeyName": "keytest",
"KeyType": "ssh-rsa",
"KeyLength": "2048",
"FingerPrint": "69:ff:8d:8e:4d:a3:79:da:fc:09:6c:e8:01:15:66:9b",
"CreatedBy": "admin",
"CreationTime": "Today"
}
]
}

4.To fetch a particular SSH key

Description:

To fetch a particular SSH keys from the discovered keys

HTTPS method:

POST

Input data:

The name of the operation and key to be passed as input

{"operation":{"Details":{"keyName":"key"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/getSSHKey?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE&INPUT_DATA={"operation":{"Details":{"keyName":"key"}}}

Sample response:

{
"name": "GetSSHKey",
"result": {
"status": "Success",
"message": "SSH Key key fetched successfully"
},
"SSHKey": [
{
"KeyName": "key",
"KeyType": "ssh-rsa",
"KeyLength": "2048",
"FingerPrint": "4b:97:8d:aa:8d:73:89:7c:96:69:7d:10:df:b2:d0:af",
"CreatedBy": "admin",
"CreationTime": "1 days"
}
]
}

5.To export an SSH key

Description:

To export a particular SSH key

HTTPS METHOD:

POST

Input data:

The name of the operation and key to be passed as input

{"operation":{"Details":{"keyName":"key"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/exportSSHKey?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE&INPUT_DATA={"operation":{"Details":{"keyName":"key"}}}

Sample response:

Key file

6.To GET SSH keys for a user

Description:

To get all the SSH keys associated with a particular user

HTTPS method:

GET

Input data:

The user name and resource name to be passed as input

{"operation":{"Details":{"userName":"test","resourceName":"172.21.147.80"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/getSSHkeysforuser?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE&INPUT_DATA={"operation":{"Details":{"userName":"test","resourceName":"172.21.147.80"}}}

Sample response:

{
"name": "GetSSHKeysForUser",
"result": {
"status": "Success",
"message": "SSH keys for user test of resource 172.21.147.80 fetched successfully"
},
"Keys": "key,keytest"
}

7.To enumerate all users

Description:

To enumerate all users in a particular resource

HTTPS method:

POST

Input data:

The user name and resource name to be passed as input

{"operation":{"Details":{"userName":"test","resourceName":"172.21.147.80"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/enumerateusers?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE&INPUT_DATA={"operation":{"Details":{"userName":"test","resourceName":"172.21.147.80"}}}

Sample response:

{
"name": "EnumerateUsers",
"result": {
"status": "Success",
"message": "User enumeration started"
}
}

8.To GET all SSH users

Description:

To get all the discovered SSH users

HTTPS method:

GET

Input data:

None

Sample request:

https://<HostName>:6565/api/pki/restapi/getAllSSHUsers?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE

Sample response:

{
"name": "GetAllSSHUsers",
"result": {
"status": "Success",
"message": "All SSH Users fetched successfully"
},
"totalRows": 2,
"AllSSHUsers": [
{
"UserName": "test",
"ResourceName": "172.21.147.80"
},
{
"UserName": test1,
"ResourceName": "172.21.147.80"
}
]
}

9.To fetch all associated users

Description:

To fetch all the users associated with SSH keys

HTTPS method:

GET

Input data:

None

Sample request:

https://<HostName>:6565/api/pki/restapi/getAllAssociatedUsers?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE

Sample response:

{
"name": "GetAllAssociatedUsers",
"result": {
"status": "Success",
"message": "All associated users fetched successfully"
},
"totalRows": 1,
"AllAssociatedUsers": [
{
"UserName": "test",
"ResourceName": "172.21.147.80"
}
]

10.To GET all the keystore keys

Description:

Keystore: Key Manager Plus provides a repository called keystore to securely store your digital keys. To fetch all the keys from keystore

HTTPS method:

GET

Input data:

None

Sample request:

https:// <HostName> :6565/api/pki/restapi/getAllKeyStoreKeys?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE

Sample response:

{
"name": "getAllKeyStoreKeys",
"result": {
"status": "Success",
"message": "All KeyStore Keys fetched successfully"
},
"totalRows": 1,
"data": [
{
"Description": "test",
"Key Name": "cert.cer",
"Created Time": "Sep 27, 2016 12:27",
"Datacenter": "Central US",
"Instance Name": "test",
"Key Type": "test",
"Created By": "admin"
}
]
}

11.To export a keystore key

Description:

To export a particular key from the keystore

HTTPS method:

POST

Input data:

The key name to be passed as input.

{"operation":{"Details":{"keyName":"cert.cer"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/exportKeyStoreKey?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE&INPUT_DATA={"operation":{"Details":{"keyName":"cert.cer"}}}

Sample response:

Key file

12.To delete a keystore key

Description:

To delete a key from the keystore

HTTPS method:

DELETE

Input data:

The key name to be passed as input.

{"operation":{"Details":{"keyName":"cert.cer"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/deleteKeyStoreKey?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE&INPUT_DATA={"operation":{"Details":{"keyName":"cert.cer"}}}

Sample response:

{
"name": "DeleteKeyStoreKey",
"result": {
"status": "Success",
"message": "Key Store keys deleted successfully"
}
}

13.To add a keystore key

Description:

To add a new key to the keystore

HTTPS method:

POST

Input data:

The following data to be passed as input.

{"operation":{"Details":{"keyName":"brin.cer",
"description":"test",
"datacenter":"test",
"passphrase":"test",
"keyType":"test",
"instanceName":"test"}}} -F File=@E:/certs/cert.cer

Sample request:

curl -X POST -k -H 'Content-Type: multipart/form-data' -F INPUT_DATA={"operation":{"Details":{"keyName":"brin.cer","description":"test","datacenter":"test","passphrase":"test","keyType":"test","instanceName":"test"}}} -F File=@E:/certs/cert.cer https://<HostName>:6565/api/pki/restapi/addKeyStoreKey?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE

Sample response:

{"Status":"Success","Message":"Key added to key store successfully"}

14.To update a keystore key

Description:

To update a particular keystore key

HTTPS method:

POST

Input data:

The following data to be passed as input.

{"operation":{"Details":{"keyName":"brin.cer",
"description":"test",
"datacenter":"test",
"passphrase":"test",
"keyType":"test",
"instanceName":"test"}}} -F File=@E:/certs/cert.cer

Sample request:

curl -X POST -k -H 'Content-Type: multipart/form-data' -F INPUT_DATA={"operation":{"Details":{"keyName":"brin.cer","description":"test","datacenter":"test","passphrase":"test","keyType":"test","instanceName":"test"}}} -F File=@E:/certs/cert3.cer https://<HostName>:6565/api/pki/restapi/updateKeyStoreKey?AUTHTOKEN=99AE42A9-02E0-4638-888A-D4D19225C3FE

Sample response:

{"Status":"Success","Message":"Key Store key updated successfully"}

15.To GET a certificate

Description:

To obtain a certificate from KMP's certificate repository

HTTPS method:

GET

Input data:

The operation details and the name of the certificate fetched to be passed as input

{"operation":{"Details":{"common_name":"*.google.com"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/getCertificate?AUTHTOKEN=3E014D78-E603-413A-AC24-6392F0001283&INPUT_DATA={"operation":{"Details":{"common_name":"*.google.com"}}}

Sample response:

Certificate object

16.To GET all certificates

Description:

To obtain all certificates from KMP's certificate repository

HTTPS method:

GET

Input data:

None

Sample request:

https://<HostName>:6565/api/pki/restapi/getAllSSLCertificates?AUTHTOKEN=3E014D78-E603-413A-AC24-6392F0001283

Sample response:

{"name":"GetAllSSLCertificates","result":{"status":"Success","message":"All SSL
Certificates fetched successfully"},"totalRows":1,"SSLCertificates":[{"CertID":1,"DNS
Name/FQDN":"ec2-54-243-44-216.compute-1.amazonaws.com","Port":443,"Common Name":"*.acquia-sites.com",
"Issuer":"Acquia Inc","FromDate":"Sep 3, 2009","ExpiryDate":"Sep 3,
2010","KeyStrength":"1024"}]}

17.To GET all certificate expiry

Description:

To get the expiry dates of all the certificates

HTTPS method:

GET

Input data:

None

Sample request:

https://<HostName>:6565/api/pki/restapi/getAllSSLCertsExpiryDate?AUTHTOKEN=1B2BF6FA-8511-47A8-867D-CE7FFE4BFBD0

Sample response:

{"name":"GetAllSSLCertificatesExpiryDate","result":{"status":"Success","message":"Certificates expiry date fetched successfully"},"totalRows":1,"SSLCertificates_Expiry_Date":[{"Common Name":"*.acquia-sites.com","ExpiryDate":"Sep 3, 2010"}]}

18.To GET certificate details

Description:

To get the details of a particular certificate

HTTPS method:

GET

Input data:

The operation details and the name of the certificate to passed as input

{"operation": {"Details":{"common_name":"*.google.com"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/getCertificateDetails?AUTHTOKEN=3E014D78-E603-413A-AC24-6392F0001283&INPUT_DATA={"operation": {"Details":{"common_name":"*.google.com"}}}

Sample response:

{"name":"GetCertificateDetails","result":{"status":"Success","message":"Details of certificate
apitest fetched
successfully"},"endpoint":{"hostName":"apitest","port":443,"expiry_date":"2016-11-15
15:05:10.0","from_date":"2016-09-16
15:05:10.0","certSignAlg":"SHA256withRSA","Sans":"","serial":"3472ac6d","fingerPrint":"1afa050
78aacf702e4ae7e84f182a817eea96c46","keyalg":"RSA","PublicKeyLength":2048,"PrivateKey":true},
"issuer":{"cname":"apitest","org":"apit","orgunit":"apitest"},"issuedto":
{"cname":"apitest","org":"apit","orgunit":"apitest"},"intermediate":{}}

19.To GET certificate keystore

Description:

To get the key store file of a particular certificate

HTTPS method:

GET

Input data:

The name of the operation and the common name of the keystore file to be passed as input

{"operation":{"Details":{"common_name":"apitest"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/getCertificateKeyStore?AUTHTOKEN=3E014D78-E603-413A-AC24-6392F0001283&INPUT_DATA={"operation":{"Details":{"common_name":"apitest"}}}

Sample response:

KeyStore File Object

20.To delete a certificate

Description:

To delete a certificate from KMP's repository

HTTPS method:

DELETE

Input data:

The operation name and the common name of the certificate to be passed as input

{"operation": {"Details":{"common_name":"apitest"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/deleteCertificate?AUTHTOKEN=3E014D78-E603-413A-AC24-6392F0001283&INPUT_DATA={"operation": {"Details":{"common_name":"apitest"}}}

Sample response:

{"name":"DeleteCertificate","result":{"status":"Success","message":"Certificate apitest deleted successfully."}}

21.To perform resource discovery

Description:

To discover a particular resource for SSL certificates

HTTPS method:

POST

Input data:

The name/IP address of the host and port number to be passed as input

{"operation":{"Details":{"HOST":"de-ubuntu10-1","TIMEOUT":"300","PORT":"6565"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/sslCertSingleDiscovery?AUTHTOKEN=3E014D78-E603-413A-AC24-6392F0001283&INPUT_DATA={"operation":{"Details":{"HOST":"de-ubuntu10-1","TIMEOUT":"300","PORT":"6565"}}}

Sample response:

{
"name": "Get SSL Discovery",
"totalRows": 1,
"de-ubuntu10-1": [
"SUCCESS",
"SSL Certificate discovered, demo.keymanager.com certificate found at port 6565"
]
}

22. To perform resource discovery (for a range of IP addresses)

Description:

To discover a set of resources for SSL certificates

HTTPS method:

POST

Input data:

The start and end IP addresses, port number and time-out to be passed as input

{"operation":{"Details":{"StartIpAddress":"192.168.216.0",
"EndIpAddress":"192.168.216.3",
"TIMEOUT":"3",
"PORT":"443"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/sslCertRangeDiscovery?AUTHTOKEN=7EDC4ED5-E684-4413-9848-F0016C114874&INPUT_DATA={"operation":{"Details":{"StartIpAddress":"192.168.216.0","EndIpAddress":"192.168.216.3","TIMEOUT":"3","PORT":"443"}}}

Sample response:

{ "name": "Get SSL Discovery",
"totalRows": 4,
"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.3": [
"FAILURE",
"Connection timed out,no certificate found at port 443"
],
"192.168.216.2": [
"FAILURE",
"Connection timed out,no certificate found at port 443"
]
}

23. To create CSR

Description:

To create a certificate signing request

HTTPS method:

POST

Input data:

The following data need to be passed as input.

{"operation":{"Details":{"CNAME":"mytestcert",
"ALT_NAMES":"test",
"ORGUNIT":"hhh",
"ORG":"h",
"LOCATION":"hh",
"STATE":"h",
"COUNTRY":"hh",
"PASSWORD":"bbbbbbbb",
"VALIDITY":"888",
"ALG":"RSA",
"LEN":"4096",
"SIGALG":"SHA256",
"StoreType":"PKCS12"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/createCSR?AUTHTOKEN=C6506112-6113-42C9-AD3
F-4A3AEF9476C9&INPUT_DATA={"operation":{"Details":{"CNAME":"mytestcert","ALT_NAMES":"test","ORGUNIT":
"hhh","ORG":"h","LOCATION":"hh","STATE":"h","COUNTRY":"hh","PASSWORD":"bbbbbbbb",
"VALIDITY":"888","ALG":"RSA","LEN":"4096","SIGALG":"SHA256",
"StoreType":"PKCS12"}}}

Sample response:

{"name":"CreateCertificate","result":{"status":"Success","message":"CSR saved successfully"}}

24. To create certificate

Description:

To create an SSL certificate

HTTPS method:

POST

Input data:

The following data to be passed as input.

{"operation":{"Details":{"CNAME":"mytestcert",
"ALT_NAMES":"test",
"ORGUNIT":"hhh",
"ORG":"h",
"LOCATION":"hh",
"STATE":"h",
"COUNTRY":"hh",
"PASSWORD":"bbbbbbbb",
"VALIDITY":"888",
"ALG":"RSA",
"LEN":"4096",
"SIGALG":"SHA256",
"StoreType":"PKCS12"}}}

Sample request:

https://<HostName>:6565/api/pki/restapi/createCertificate?AUTHTOKEN=C6506112-6113-42C9-
AD3F-4A3AEF9476C9&INPUT_DATA={"operation":{"Details":{"CNAME":"mytestcert","ALT_NAMES":"test","ORGUNIT":
"hhh","ORG":"h","LOCATION":"hh","STATE":"h",
"COUNTRY":"hh",
"PASSWORD":"bbbbbbbb",
"VALIDITY":"888","ALG":"RSA","LEN":"4096","SIGALG":"SHA256","StoreType":"PKCS12"}}}

Sample response:

{"name":"CreateCertificate","result":{"status":"Success","message":"Certificate saved successfully"}}

25. To Import an SSH key

Description:

To import an SSH key

HTTPS method:

POST

Input data:

The following data to be passed as input.

{"operation":{"Details":{"keyName":"testkey","passphrase":"passtrix"}}}

Sample request:

curl -X POST -k -H 'Content-Type: multipart/form-data' -F
INPUT_DATA={"operation":{"Details":{"keyName":"testkey","passphrase":"passtrix"
}}} -F File=@D:/certs/keys/test1-passtrix/test1_Jul-21-2017-15_56.key
https://:6565/api/pki/restapi/addSSHKey?AUTHTOKEN=A3164150-4C1
5-4AA4-918E-F258F38149F8

Sample response:

{"name":"addSSHKey","result":{"status":"SUCCESS","message":"Key imported
successfully"}}

26. To associate an SSH key

Description:

To associate an SSH key

HTTPS method:

POST

Input data:

The following data to be passed as input.

{"operation":{"Details":{"keyName":"testkey","resourceName":"test.csez.zohocorpi
n.com","userName":"test"}}}

Sample request:

https://:6565/api/pki/restapi/associateKey?AUTHTOKEN=A3164150-4C
15-4AA4-918E-F258F38149F8&INPUT_DATA={"operation":{"Details":{"keyName":"te
stkey","resourceName":"test.csez.zohocorpin.com","userName":"test"}}}

Sample response:

{
"name": "associateKey",
"result": {
"status": "Success",
"message": "Key associated successfully "
}
}

27. To Dissociate an SSH key

Description:

To dissociate an SSH key

HTTPS method:

POST

Input data:

The following data to be passed as input.

{"operation":{"Details":{"keyName":"testkey","resourceName":"test.csez.zohocorpi
n.com","userName":"test"}}}

Sample request:

https://:6565/api/pki/restapi/dissociateKey?AUTHTOKEN=A3164150-4C
15-4AA4-918E-F258F38149F8&INPUT_DATA={"operation":{"Details":{"keyName":"te
stkey","resourceName":"test.csez.zohocorpin.com","userName":"test"}}}

Sample response:

{
"name": "dissociateKey",
"result": {
"status": "SUCCESS",
"message": "Key dissociated successfully."
}
}