Kiwire 2.0 Documentation

  1. Home
  2. Docs
  3. Kiwire 2.0 Documentation
  4. Integrations
  5. API

API

Kiwire has a built in API (Application Protocol Interface) that let your application connect and manipulate system and retrieve data from your own developed application. For optional reading, Technical information on the Kiwire API specification will be included below. To access the API module click on Integrations > API from the navigation. The configuration screen will be displayed. This includes main and permission for Kiwire platform.

The field and its function description is listed below.

FieldFunction
EnabledEnable or disable API access.
Authentication KeyShared secret key between your application and Kiwire when communicate, type in a shared key or use “Generate Key” button to generate one.

API Permission

The API permission tab enables you to configure the API permission given to the connecting application. Use “toggle” to enable the permission of the API interface to 3rd party.

The field and its function description is listed below.

API PermissionDescription
Add UserAdd user function.
Update UserUpdate user function.
Delete UserDelete user function.
Add AdminAdd administrator.
Update AdminUpdate admin function.
Delete AdminDelete administrator.
Add NASAdd NAS.
Update NASUpdate NAS function.
Delete NASDelete NAS.
Add DeviceAdd device function.
Update DeviceUpdate device function.
Delete DeviceDelete device function.
Add Profile/PlanAdd profile function.
Update Profile/Plan Update profile function.
Delete Profile/PlanDelete profile function.
User InformationRetrieve users information.
Login RecordRetrieve users login records.

Supported Modules

Currently, Kiwire supports API for the following modules :

  • Admin user
  • NAS
  • Devices
  • Profile
  • Login
  • User
  • Voucher

General Result

Every API request send to Kiwire will be respond as a JSON object with the below structure;

  • is_success – boolean (always true)
  • result_msg – string (message generated as a result of a request)
  • ret_data – array (items for get method)

Additionally, Kiwire also will respond with an error message based on the below structure;

  • error – string (error message)

API Login

Every API request needs to perform login to obtain token key which then will be used to make request to module.

URL – http://{{kiwire_ip}}/admin/agent/api_login.php

Parameters Required

ParameterDescription
codeMD5 hashed of the username|password
Example: username is hakim and password is admin, then the code will be md5(“hakim|admin”) = 404ad50c254f12a606ae68d0338e86a9
cloud_idCloud ID or Tenant name of the API key

Response

{
"status": "success",
"token": "80d588720c2203739ad643d405e63136"
}

Notes

This action will create an API session inside Kiwire which expires after 20 minutes. You have to re-login after 20 minutes to make another API request.

The token provided will be use in all API request.

Module: Login

URL

[POST] http://{{kiwire_ip}}/apiv2/login/{{method}}/{{value}}

Where {{method}} can be:

  • history : List of sessions created for particular account
  • online : Send request to NAS for login user device as per account provided
  • unauthorize : List of user device which are not authorised

Where {{value}} can be:

  • username : For history method
  • nas id : For unauthorize method

Parameters Required

History – List of sessions created for particular account

ParameterValueDescription
start_timedate
(Y-m-d H:i:s)
(optional) From login datetime
end_timedate
(Y-m-d H:i:s)
(optional) Until login datetime
startinteger(optional) (default: 0) Start from this row number
limitinteger(optional) (default: 50) Limit data count
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate
(Y-m-d H:i:s)
Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

*If username is not provided in this request, the session list for all user will be returned.

Online – Send request to NAS for login user device as per account provided

ParameterValueDescription
nas-idstringNAS Identity to send the request
devicestringMAC Address of the user device
ipstringIP Address of the user device
userstringUsername to be used to login user device
profilestring(optional) Profile to link user with
allownasstring(optional) Zone to restrict user
statusstring(optional) Status of user (active or suspend)
remarkstring(optional) Remark
api_keystringMD5 hashed in this format:
{real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

*Parameters marked as optional will only be used if user creation required (user not existed). If these values are not provided during the creation process, default value will be used as per below;

ParameterDefault Value
profilewx_temp, temporary 5 mins profile
allownasnone
statusactive
remarkAPI Registration

Unauthorize – List of user device which are not authorized

ParameterValueDescription
api_keystringMD5 hashed in this format:
{real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Response

{
“is_success” : “true”, // always true to indicate that the request has been processed
“result_message” : “”, // return a string of status for online method
“return_data” : [] // return items found in database for unauthorize and history
}

Module: Administrator User

URL

[POST] http://{{kiwire_ip}}/apiv2/admin/{{method}}/{{value}}

Where {{method}} can be:

  • create
  • delete
  • get

Where {{value}} can be:

  • administrator
  • username

Parameters Required

Create

ParameterValueDescription
usernamestringUsername to login into Kiwire system
groupnamestringRole for the admin
fullnamestringFull name
monitory or nSet the value to Y if this admin should receive notification email from Kiwire
emailstringEmail address to send notification
temp_passboolean(Optional) (default: true) Set value to true if this admin should change password after login
api_keystringMD5 hashed in this format:
{real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Delete

ParameterValueDescription
api_keystringMD5 hashed in this format:
{real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Get

ParameterValueDescription
api_keystringMD5 hashed in this format:
{real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key
startinteger(optional) (default: 0) Number of start data
limitinteger(optional) (default: 200) Limit data count

Notes

For get method, if {{value}} not provided then Kiwire will return all available items subject to start and limit.

Module: User Account

URL

[POST] http://{{kiwire_ip}}/apiv2/user/{{method}}/{{value}}

Where {{method}} can be:

  • create
  • delete
  • get

Where {{value}} can be:

  • user account

Parameters Required

Create

ParameterValueDescription
usernamestringUsername for wifi authentication
passwordstringPassword for wifi authentication
fullnamestringFull name
emailstringEmail Address
phonestringPhone number
profilestringInternet plan
remarkstringRemark
statusstringStatus
allownasstringEnable NAS
expirystringThe validity of account to be generated
macstringMac address associate with the user
integrationstringAuthentication integration module
statisticsstringStatistics
api_keystringMD5 hashed in this format:
{real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Delete

ParameterValueDescription
api_keystringMD5 hashed in this format:
{real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Get

ParameterValueDescription
api_keystringMD5 hashed in this format:
{real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key
startinteger(optional) (default: 0) Number of start data
limitinteger(optional) (default: 200) Limit data count

Notes

*For get method, if {{value}} not provided then Kiwire will return all available items subject to start and limit.

Module: Voucher Account

URL

[POST] http://{{kiwire_ip}}/apiv2/voucher/{{method}}/{{value}}

Where {{method}} can be:

  • create
  • delete
  • get

Where {{value}} can be:

  • voucher code

Parameters Required

Create

ParameterValueDescription
prefixstring(optional) (default: V_) Prefix for every voucher generated
qtyinteger(optional) (default: 10) Quantity of voucher generated
planstring(optional) (default: wx_temp) The profile associated with voucher to be generated
nasstring(optional) Apply zone restriction to the voucher to be generated, to be able to login from specific zone only
expirydate(optional) (default: {{tomrrow date}}) The validity of voucher to be generated
remarkstring(optional) (default: {{tomrrow date}})
Remark
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Delete

ParameterValueDescription
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Get

ParameterValueDescription
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key
startinteger(optional) (default: 0) Number of start data
limitinteger(optional) (default: 200) Limit data count

Notes

For get method, if {{value}} not provided then Kiwire will return all available items subject to start and limit.

Module: NAS

URL

[POST] http://{{kiwire_ip}}/apiv2/nas/{{method}}/{{value}}

Where {{method}} can be:

  • create
  • delete
  • get

Where {{value}} can be:

  • nas identity

Parameters Required

Create

ParameterValueDescription
nas-ipstringIP Address of the NAS devices
nas-idstringA unique name to identify the NAS equipment
typestringNAS device type
portsintegerThe ‘change of authority’ (COA) listening port of the nas device
secretstringThe Secret password that the NAS will use to communicate with Kiwire
serverstringServer
communitystringSNMP Community string
descriptionstringThe description of the NAS equipment
locationstringLocation of the NAS
usernamestringThe administrator username that is use to manage and monitor the NAS
passwordstringThe password for the administrator username used
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Delete

ParameterValueDescription
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Get

ParameterValueDescription
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key
startinteger(optional) (default: 0) Number of start data
limitinteger(optional) (default: 200) Limit data count

Notes

For get method, if {{value}} not provided then Kiwire will return all available items subject to start and limit.

Module: Devices

URL

[POST] http://{{kiwire_ip}}/apiv2/device/{{method}}/{{value}}

Where {{method}} can be:

  • create
  • delete
  • get

Where {{value}} can be:

  • voucher code

Parameters Required

Create

ParameterValueDescription
device-ipstringIP Address of the equipment
device-idstringA unique name to identify the equipment
typestringDevice type
macintegerThe ‘change of authority’ (COA) listening port of the nas device
communitystringSNMP Community string
descriptionstringThe Description for the device/equipment
locationstringLocation of the device/equipment
usernamestringThe username use to access the equipment remotely
passwordstringThe password used by the username to access the equipment
snmpvintegerVersion
mibstringManagement Information Base
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Delete

ParameterValueDescription
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Get

ParameterValueDescription
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key
startinteger(optional) (default: 0) Number of start data
limitinteger(optional) (default: 50) Limit data count

Notes

For get method, if {{value}} not provided then Kiwire will return all available items subject to start and limit.

Module: Profile

URL

[POST] http://{{kiwire_ip}}/apiv2/profile/{{method}}/{{value}}

Where {{method}} can be:

  • create
  • delete
  • get

Where {{value}} can be:

  • profile name

Parameters Required

Create

ParameterValueDescription
profile-namestringThe name of the profile/plan
pricefloatThe price of plan
typestringType of plan
edxstringIntegration to charge to or link with
minuteintegerThe allowed time (minutes)
vol_limit_en‘on’ or ‘off’Enable or disable volume transfer limit
vol_limitintegerThe limit of volume transfer (GB)
idleintegerIdle timeout of user to disconnected by system
simultaneousintegerCount of simultaneous user that use the same account associated with this plan
bwdownintegerMaximum download speed allowed for user (Kbps)
bwupintegerMaximum upload speed allowed for user (Kbps)
min_upintegerMinimum download speed allowed for user (Kbps)
min_downintegerMinimum upload speed allowed for user (Kbps)
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Delete

ParameterValueDescription
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Get

ParameterValueDescription
api_keystringMD5 hashed in this format: {real_api_key_from_kiwire}+{token}+{time}
timedate(YmdHis)Current time
Must be in this format: YmdHis
tokenstringToken generated during the API login process
cloud_idstringCloud ID or Tenant name of the API key

Notes

For get method, if {{value}} not provided then Kiwire will return all available items subject to start and limit.

Sample API Code

<?php
session_start();
// Configuration
$cloud_id = "default";
$username = "admin";
$password = "youradminpassword";
$api_key = "Nsf7a86787asvh&5asfkasdfNDJFNKsa=sS"; // API key get from Kiwire
$kiwire_host = "http://kiwireserveraddress.com";
$kiwire_port = 8081;
/* *********************
** -- START --
** LOGIN & TOKEN PART
*/
// If token already exist, check if the token expired or not
if(isset($_SESSION['login_token']) && isset($_SESSION['login_last_time'])){
$time_current = time();
$time_login_expired = strtotime("+20 minutes", $_SESSION['login_last_time']);
if($time_current < $time_login_expired) $do_not_get_token = true;
}
// If token not exist or token expired, get new token
if(empty($do_not_get_token)){
// setup api_login method to get the token
$login_api_data = Array(
"url" => $kiwire_host . "/admin/agent/api_login.php",
"port" => $kiwire_port,
"params" => Array(
"code" => MD5( $username . "|" . $password ),
"cloud_id" => $cloud_id,
),
);
// execute api_login method to get the token
$result_json = sendhttpreq($login_api_data['url'], $login_api_data['params'], "POST", $login_api_data['port']);
$result_array = json_decode($result_json, true);
$_SESSION['login_token'] = $result_array['token']; //the token will expired in 20 minutes and must renew the token each 20 minutes
$_SESSION['login_last_time']= time();
}

/*
** -- END --
** LOGIN & TOKEN PART
** ********************* */
// this $current_datetime variable
// must be included in the hashed API Key ( MD5($real_api_key . $login_token . $current_datetime) )
// also must be included in params as "time"
// - refer the code below
$current_datetime = date("YmdHis");
// set up login history method
// you can refer to documentation for another method
$api_call_data = Array(
"url" => $kiwire_host . "/apiv2/login/history",
"port" => $kiwire_port,
"params" => Array(
"start_time" => "2017-06-08 00:00:00",
"end_time" => "2017-06-08 23:59:59",
"token" => $_SESSION['login_token'],
"api_key" => MD5( $api_key . $_SESSION['login_token'] . $current_datetime ),
"time" => $current_datetime,
"cloud_id" => $cloud_id,
),
);

// execute login history method
$result_json = sendhttpreq($api_call_data['url'], $api_call_data['params'], "POST", $api_call_data['port']);
$result_array = json_decode($result_json, true);

// if login token expired, refresh to get new token
if(substr($result_array['error'], 0, 13) == "login expired"){
session_destroy();
echo "<script>window.location.reload();</script>";
}

// display the result
var_dump($result_array);

// Function for sending HTTP Request
function sendhttpreq($url, $data, $method="GET", $port=80){
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_PORT, $port);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
return $result;
}
?>

List of Error Message

Error MessageCauseSolution
permission deniedMissing token or api_key or cloud_idMust login back via API to get new token
login expired. please complete the api login againToken has expiredCurrent time
Must be in this format: YmdHis
please provide full urlURL is not validPlease refer documentation for valid URL
invalid api keyAPI key or hashed API key is incorrectMake sure the API key, token, and time is correct
api integration is currently disabledAPI integration is OFFMake sure the API integration is ON in Kiwire UI platform
module not existedURL or method is not validPlease refer documentation for valid URL or method
module disabledSelected module is OFFMake sure the module is ON in Kiwire UI platform
no tenant / cloud id providedNo Cloud ID providedPlease include cloud_id parameter in every API HTTP request
cloud id not foundCloud ID provided is not validMake sure the Cloud ID provided is valid
cloud id not availableCloud ID provided is not validMake sure the Cloud ID provided is valid
not valid userUsername or Password or Cloud ID is not matchedPlease use correct username, password and cloud ID
Was this article helpful to you? Yes No

How can we help?