Deploy an API via apictl (the CLI tool)


Before you begin

This guide assumes that you already have a Choreo Connect instance that is up and running. If not, checkout the Quick Start Guide on how to install and run Choreo Connect. To learn more about Choreo Connect, have a look at the Overview of Choreo Connect.

Step 1 - Download apictl and Set the Path Variable

First download apictl locally and extract it into a folder of your choice. Then, add its location to your PATH variable.

export PATH=$PATH:<directory-of-the-apictl-executable>

Step 2 - Create an API Project using apictl

Let's create your first project "petstore" using an open API definition. The following apictl init command will generate a project folder containing all the necessary files.


If you have used a previous version of apictl before, remember to delete the directories .wso2apictl and .wso2apictl.local that are located in your home directory. Deleting them will make the newer apictl create them again, with content compatible with the current version.

apictl init petstore --oas

Step 3 - Add an Choreo Connect Environment to apictl

To use apictl for Choreo Connect, a Choreo Connect environment needs to be added to apictl. This environment will hold the adapter URL for further commands.

apictl mg add env dev --adapter https://localhost:9843


Note mg in the above command. The apictl commands that starts as apictl mg are Choreo Connect specific. If a command does not have mg after apictl then the command could probably be common to both Choreo Connect and API Manager, but it could also be API Manager specific.


The apictl commands here onwards are executed with the -k flag to avoid SSL verification with the Choreo Connect.

To communicate via https without skipping SSL verification (without -k flag), add the cert in the Choreo Connect truststore into the <USER_HOME>/.wso2apictl/certs folder.

Step 4 - Log in to the Choreo Connect Environment in apictl

You can use the following command to log in to the above Choreo Connect cluster (in other words log in to the Choreo Connect adapter). By logging in, an access token will be retrieved from Choreo Connect and saved in apictl.

apictl mg login dev -k


apictl mg login dev -u admin -p admin -k

Step 5 - Deploy the API

Now let's deploy the API to Choreo Connect by executing the following command.

apictl mg deploy api -f <path_to_the_API_project_just_created>/petstore -e dev -k


Refer to the following content to learn more,

Step 6 - Invoke the API

After the APIs are exposed via Choreo Connect, you can invoke an API with a valid token (JWT or opaque access token).

Let's use the following command to generate a JWT to access the API, and set it to the variable TOKEN.

TOKEN=$(curl -X POST "https://localhost:9095/testkey" -H "Authorization: Basic YWRtaW46YWRtaW4=" -k -v)
Execute the following cURL command to Invoke the API using the JWT.

curl -X GET "https://<CHOREO-CONNECT_ROUTER_HOST>:<CHOREO-CONNECT_ROUTER_PORT>/<API-context>/<API-resource>" -H "accept:application/xml" -H "Authorization:Bearer $TOKEN" -k
curl -X GET "https://localhost:9095/v2/pet/findByStatus?status=available" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k

Refer to Generate a Test JWT for more details.