Getting started with the Kerio Product APIs

The Kerio API enables you to programmatically access your Kerio Connect, Kerio Control, and Kerio Operator servers to integrate with third-party solutions or write scripts to automate specific tasks. The API provides all actions available in the web interfaces of each product. For example, you can add/remove users, update IP address groups, read logs, manage time ranges, and much more.

Licensing

The Kerio administration API is a part of the Kerio products and is governed by the product’s license. In summary, you need a license to run Kerio products and the license also entitles you to use the API on your server. Third-party independent software vendors may distribute their applications both for free or for profit. There is no royalty fee for using the API.

Get involved

Kerio maintains a dedicated forum for sharing your ideas, questions, answers, and other feedback with the developer community. You can participate in the forum at forums.kerio.com.

Introduction

The Kerio API is accessible via a secure, session based HTTP connection. All communication is formatted as a JSON string and directed to a designated URL. For example, a request for the Kerio Connect administration API may go to https://server.example.com:4040/admin/api/jsonrpc/

The URL to access the API consists of the following parts:

1. Protocol - The API uses HTTPS
2. Hostname - The Internet accessible hostname (domain name) of your server
3. Port - The port number for accessing the API
4. File path - The file path of the JSON interface

You can learn more about the composition of a URL through the Mozilla Foundation documentation.

The port number and file path vary depending on the Kerio product and interface. Refer to the table below:

Product interface	Port	File path
Kerio Operator Softphone	443	/myphone/api/jsonrpc/
Kerio Operator Administration	4021	/admin/api/jsonrpc/
Kerio Control Statistics	4081	/lib/api/jsonrpc/
Kerio Control Administration	4081	/admin/api/jsonrpc/
Kerio Connect Administration	4040	/admin/api/jsonrpc/
Kerio Connect Client	443	/webmail/api/jsonrpc/

Prerequisites

To access the API, you need a user account on the corresponding Kerio Product. Depending on the interface, this may be a standard user account, or an administrator account with elevated permissions. The type of account you use to authenticate determines your permissions when accessing the API. In order to communicate with the API you need a framework for processing the requests and managing the network connection. A common framework for these actions is PHP and cURL.

Authentication

The Kerio API uses a two step authentication process. The first authentication step involves a username and password, the same type of account you use to access the Kerio product interface (e.g. Kerio Connect Client). After successful authentication, the API returns a randomized token, and a session cookie. All subsequent requests to the API must include the token and session cookie in the HTTP headers of the connection.

API Requests

All requests to the Kerio API must be encoded as a JSON string. The JSON string is an array consisting of the JSON version, an identifier, the API method, and the parameters of the query. You can use a web browser to inspect the JSON request and response for any interaction with your Kerio product. Refer to Inspecting Kerio API communication in a web browser for details.

Example API Communication

The following example uses PHP and cURL to get the next available extension number from a Kerio Operator server.

//Custom variables
$api_cookie="/tmp/kerio-api-cookie";
$api_url="https://operator.example.com:4021/admin/api/jsonrpc/";
$api_user="admin-api";
$api_password="secretpassword”;

//Initialize the cURL request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);  
curl_setopt($ch, CURLOPT_HTTPHEADER, "Content-Type:application/json");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_COOKIEJAR, $api_cookie); 
curl_setopt($ch, CURLOPT_COOKIEFILE, $api_cookie); 

//Server login request to obtain the API token and session cookie 
$api_login = array(
  'jsonrpc' => '2.0',
  'id' => 1,
  'method' => 'Session.login',
  'params' => array(
    'userName' => $api_user,
    'password' => $api_password,
    'application' => array(
      'name' => 'Sample app',
      'vendor' => 'Kerio',
      'version' => '1.0'
    )
  )
);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($api_login));
$return=json_decode(curl_exec($ch),true);
$token=$return['result']['token']; 

//Verify the token, otherwise return the JSON response and exit the script.
if ($token=="") {printf(htmlspecialchars($json_return)); exit();}

//Add the token to the cURL headers
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type:application/json","X-Token:".$token));

//Get the next available extension number
$api_query = array(
  'jsonrpc' => '2.0',
  'id' => '1',
  'method' => 'Extensions.getNextValidNumber',
  'params' => array()
);
curl_setopt($ch, CURLOPT_POSTFIELDS,json_encode($api_query));
$return=json_decode(curl_exec($ch),true);
$next_ext=$return['result']['extensionNumber'];

curl_close($ch);