WSO2 API Manager — Managing Back-end Certificates has been revolutionized….

Menaka Jayawardena
4 min readDec 10, 2017


How to add a back-end certificate to WSO2 API Manager? If you already have any experience with it these might be the steps that you have followed.

  1. Import the certificate to API Manager client-truststore.
  2. Restart the server.

Easy. Right? :-)


But, every time you import a certificate to the trust store, you have to restart the server. If it’s a cluster, add to each api manager gateway instance one-by-one and restart them.

With the latest feature of the API Manager, you can add and manage the certificates of your api back-end without restarting the server. And most interestingly, you can do it at the time of publishing a new API.

In this article, let’s see how to make use of this feature in WSO2 API Manager.

Before we proceed, here are the per-requisites…

  1. You have to install the latest updates for API Manager 2.1.0 through WSO2 Update Manager. And carefully read the instructions and apply the updates to your deployment. Here is how to do it.
  2. This feature only supports standard Java Keystores and .crt, .cert certificate formats. So, if you have any other type of Keystore for your client trust store, you have to convert it to the JKS format.
  3. Make sure your back-end certificate has not expired.

Adding a back-end certificate for an API.

To add a certificate to a new API, first you have to start publishing an API. For this example I’m using the “Design a New Rest API”.

Create new API

In the next step, enter the general information (API Name, Context, version and resources..) for our API. I have developed a simple echo service which prints “Jersey say : {name}” which is running on a local tomcat server which is running on

And click on Next: Implement >.

API Design View

In the API Implementation step, we specify the production and sandbox endpoints for our api. Add the https back-end url for production and sandbox endpoints.

We can add the certificate for the end points in this step. But, for the clarification in this article, I’m going to invoke the api without adding the certificate first.

So, after adding the endpoints, I click “Next: Manage >” and go to the next step.

API Implementation view

In the Manage step, select the tier and publish the api.

Next, I invoke the api as usual in WSO2 API Manager. I’m not going to discuss how to subscribe to an API and invoking it. If you are new to WSO2 API Manager, please follow this documentation [1].

I invoked the api by following cURL command and I got an error.

curl -X GET — header ‘Accept: application/json’ — header ‘Authorization: Bearer <token>’ ‘https://localhost:8243/test/1.0/menaka' -k<am:fault xmlns:am=”"> 
<am:type>Status report</am:type>
<am:message>Runtime Error</am:message>
<am:description>Error in Sender</am:description>

When I observe the API Manager back end, there is an SSL Exception which saying, it could not find a proper certificate for the back-end.

Caused by: PKIX path building failed: unable to find valid certification path to requested target

Let’s add the certificate now.

Go to the API that we just created, click on Edit and go to API Implementation step.

Click on “Manage Certificates”.

Click on Manage Certificates.
No uploaded Certificates

As we do not have any certificates uploaded it will say, No Uploaded Certificates.

Let’s upload a certificate.

  1. Click on Add New Certificate button.
  2. Enter the certificate Alias.
  3. Select the endpoint of the certificate.
  4. Click Upload.
Upload Certificate Modal

The uploaded certificate will be listed as follows. Also if you need to upload multiple certificates it can also be done.

The certificate that we just uploaded.

After you upload the certificate, it will take 10 mins to take effect. (Also you can minimize the time to 5mins. More details in a separate article)

After 5mins, I again invoked the api….. Same curl command.

curl -X GET — header ‘Accept: application/json’ — header ‘Authorization: Bearer <token>’ ‘https://localhost:8243/test/1.0/menaka' -k

Here is the result:

Jersey say : menaka

Yes…! It worked.

So, in this way, you can add certificates to your backends without even touching any file and restarting the server. For the official documentation of this feature, please refer [2]

Please note the following facts when using this feature.

  1. You could not add multiple certificates for the same endpoint or with the same alias.
  2. You could not add expired certificates.



See you again….