Content

The following sections explain REST APIs and how you can use them:

• Overview of REST APIs 

• IBM Security Key Lifecycle Manager REST APIs

• Steps to use the IBM Security Key Lifecycle Manager REST APIs

• How-To Videos

REST API Overview

A REST application programming interface (API) enables client applications to access and manage resources on a server by sending requests and receiving responses using the HTTP or HTTPS protocols. 

REST API - Clients

You can use any client or programming language that can submit an HTTP or HTTPS request. Some utilities that provide non-programming interfaces:

• Curl 

• REST clients for browsers, such as REST Client for Firefox

• Postman

• Requester

Back to top

IBM Security Key Lifecycle Manager REST APIs

The IBM Security Key Lifecycle Manager REST APIs provide access to the product resources (services and functions), and enable other applications to integrate with the product.  The REST APIs comprise methods to perform operations, such as manage certificates, keys, master keys, and so on.

REST API Request

An IBM Security Key Lifecycle Manager REST API request comprises the following four parts:

  https://<host>:<port>/SKLM/rest/v1/ckms/login

  POST

  Content-Type: application/json  

  {"userid":"admin1","password":"pswd"}

Where:
<host> is the fully qualified host name of the IBM Security Key Lifecycle Manager server.
<port> is the port to access the server.

REST API Response
IBM Security Key Lifecycle Manager supports the JSON response format, which comprises the following two parts:

  Status Code : 200 OK  Content-Language : en

  {"userAuthId":"37ea1939-1374-4db7-84cd-14e399be2d20"}

Back to top

REST Client for Firefox Example

The REST Client for Firefox is an add-on for the Mozilla Firefox browser that sends REST requests and receives REST responses without a programming effort.
To install the REST Client for Firefox, go to  https://addons.mozilla.org/en-US/firefox/addon/restclient/ . 
After installation, to use the REST Client for Firefox, open the Mozilla Firefox browser and click the icon on the toolbar, as shown below:

Example – Request:

Example - Response:

Curl REST Client Example

Curl is a command line tool to transfer data from or to a server. It can be used to run REST APIs.
Curl can be used on both Windows and Linux/Unix servers.

To install Curl on Windows:

1. Go to  http://curl.haxx.se/download.html and according to your server specification (32 bit / 64 bit), download the required zip file.

2. Unzip the file. 

3. Copy curl.exe file to C:\windows\System32 folder. You can now run curl.exe from the command line.

Curl libraries exist on Linux and UNIX servers by default.

Example – Request and Response:

Note: The URL in the example shows sample host and port information (10.10.10.100).  Also, the password value is blurred on purpose. If you use this REST API request, you must replace them with values that are specific to your IBM Security Key Lifecycle Manager server.

Back to top

Using the IBM Security Key Lifecycle Manager REST APIs

You must have a REST API client to use the REST APIs.

Steps to use the REST APIs:

1. Authenticate: Log in to the IBM Security Key Lifecycle Manager server and authenticate yourself.

2. Send the REST API request: Send the required IBM Security Key Lifecycle Manager REST API request.

3. Review the response.

The following sections explain each step in detail.

Step 1: Authenticate
Before you can send any REST API request to access a resource, you must log in to the IBM Security Key Lifecycle Manager server and authenticate yourself with valid user credentials. 

Use the Login REST API to do so.  This REST API validates the credentials and returns a unique user authentication identifier for all subsequent API requests.  This unique authentication identifier is required in the other REST API requests.

Request: 

  curl https://<host>:<port>/SKLM/rest/v1/ckms/login -H "Accept:application/json" -H "Content-Type:application/json" -H "Accept-Language:en-US" --data "{\"userid\":\"SKLMAdmin\",\"password\":\"SKLM@admin123\"}" -X POST -k

Successful response:

  {"UserAuthId":"87aa2002-c4f4-4523-a2a6-31d87026c4ba"}  

Step 2: Send a REST API Request

Send the required REST API request. Use the userAuthId value from the response of the Login REST API in the request.

The following example uses Create Certificate REST API.

Request:

  curl https://<host>:<port>/SKLM/rest/v1/certificates -H "Content-Type:application/json" -H "Authorization:SKLMAuth userAuthId=87aa2002-c4f4-4523-a2a6-31d87026c4ba" -d @json.txt -X POST -k  

Note: In the above Request, a sample userAuthId value is used. You must use the value that is returned when you run the Login REST API.

Also, the Request Body is provided in a file (json.txt). Content of the json.txt file:

  {"type":"selfsigned","alias":"sklmcert","cn":"sklm","ou":"sales","o":"myCompanyName","usage":"3592","country":"US","validity":"999","algorithm": "RSA"}

    {"code":"CTGKM6004E","message":"CTGKM6004E User is not authenticated or has already logged out."

Step 3: Review the Response
If the REST API request run is successful, you will receive the following response:

  {"status":"CTGKM0503I  Created a key pair and self-signed certificate: sklmcert "}

If the REST API request returns an error, you will receive the following response:

   {"code":"CTGKM0525E","message":"CTGKM0525E Parameter value(s) are not valid. alias already exists:sklmcert"}    

For this example, you can confirm that the certificate is created by logging in to the graphical user interface of the product and viewing the list of certificates.

Back to top

How-to Videos