Kerio Control API

The Kerio Control API enables you to programmatically access your Kerio Control server to integrate with third-party solutions or write scripts to automate specific tasks. The API provides all actions available in the client and administration interfaces of the product. For example, you can add/remove users, update IP addressAn identifier assigned to devices connected to a TCP/IP network. groups, read logs, manage time ranges, and much more.

Licensing

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

Get involved

A dedicated forum is available 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 API is accessible via a secure, session based HTTPHypertext Transfer Protocol - protocol for exchange of hypertext documents in HTML. connection. All communication is formatted as a JSON string and directed to a designated URL. For example, a request for the Kerio Control administration API may go to:

https://server.example.com:4081/admin/api/jsonrpc/

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

URL part	Title	Description
https://	Protocol	The API uses HTTPSHypertext Transfer Protocol - version of HTTP secured by SSL.
server.example.com	Hostname	The Internet accessible hostname (domain name) of your server
:4081	Port	The port number for accessing the API
/admin/api/jsonrpc/	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 Kerio Control API is accessible via two separate interfaces that provide different functionality. The Kerio Control Statistics interface provides reporting data on user and host activities. The Kerio Control Administration interface configures all server based functionality such as adding users, creating traffic rules, or viewing traffic charts. The port is the same, however the path varies depending on the interface.

Refer to the table below:

Product interface	Port	File path
Kerio Control Statistics	4081	/client/api/jsonrpc/
Kerio Control Administration	4081	/admin/api/jsonrpc/

Prerequisites

To access the API, you need a Kerio Control user account. 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 API uses a two step authentication process. The first authentication step involves a username and password, the same type of account used to access the Kerio Control interface. 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. The method for handling the session cookie and token depends on the framework used in your application. Refer to the example below for information on how you can manage authentication to the API using cURL.

API Requests

All requests to the 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 the product interface. For more information refer to Inspecting Kerio Control API communication in a web browser.

Example API Communication

The following example uses PHP and cURL to list the active hosts.

//Custom variables
$api_cookie="/tmp/kerio-api-cookie";
$api_url="https://control.example.com:4081/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_SSLSecure Sockets Layer -  A protocol that ensures integral and secure communication between networks._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));
 
//List all active hosts
$api_query = array (
  'jsonrpc' => '2.0',
  'id' => 1,
  'method' => 'ActiveHosts.get',
  'params' => 
  array (
    'query' => 
    array (
      'limit' => 2000,
      'start' => 0,
      'orderBy' => 
      array (
        0 => 
        array (
          'columnName' => 'currentDownload',
          'direction' => 'Asc',
        ),
      ),
    ),
    'refresh' => true,
  ),
);

curl_setopt($ch, CURLOPT_POSTFIELDS,json_encode($api_query));
$return=json_decode(curl_exec($ch),true);
$active_hosts=$return['result']['list'];
 
curl_close($ch);