Kerio Operator API

The Kerio Operator API enables you to programmatically access your Kerio Operator 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 address groups, read logs, manage time ranges, and much more.

Licensing

The API is part of Kerio Operator and is governed by the product’s license. In summary, the license to use Kerio Operator 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 HTTP connection. All communication is formatted as a JSON string and directed to a designated URLThe Uniform Resource Locator is the address of a web page on the world wide web.. For example, a request for the Kerio Operator administration API may go to:

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

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

URL part	Title	Description
https://	Protocol	The API uses HTTPS
server.example.com	Hostname	The Internet accessible hostname (domain name) of your server
:4021	Port	The port number for accessing the API
/admin/api/jsonrpc/	File path	The file path of the JSON interface

The Kerio Operator API is accessible via two separate interfaces that provide different functionality. The Kerio PhoneA softphone available as a native desktop or web-based application. interface provides phone functionality such as adding favorites, reviewing recent calls, or setting up call forwarding. The Kerio Operator Administration interface configures all server based functionality such as adding users, configuring SIPSession Initiation Protocol - A communication protocol used for voice and video calls in Internet telephony or private IP telephone systems. interfaces, or assigning extensions. The port number and file path vary depending on the interface.

Refer to the table below:

Product interface	Port	File path
Kerio Phone	443	/myphone/api/jsonrpc/
Kerio Operator Administration	4021	/admin/api/jsonrpc/

Prerequisites

To access the API, you need a Kerio Operator 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 Operator 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. Refer to Inspecting the Kerio Operator 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.

//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_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));
 
//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);