API Reference

Overview

LicenTra provides a REST-like API for complete automation of your license management workflow. The API allows you to add and edit banned hosts, clients, installations, licenses and products, and to search across all record types - all from your own external tools, scripts or websites.

The API is disabled by default and can be turned on in Settings » Security (API_STATUS in the database). It is also possible to enable whitelisted access, which only allows API calls coming from whitelisted IP addresses (Settings » Advanced).

All requests are made with HTTP POST to the central entry point. Requests are only accepted from automated User-Agents (LicenTra Custom Post or LicenTra cURL) - browsers are not able to call the API directly.

Authentication

Every API request must include a valid API key secret. API keys are created and managed in the administration dashboard under API Keys:

• Secret - the API key value submitted with every request (api_key_secret);
• IP address - optional comma-separated list of IP addresses from which the key may be used. Leave empty to allow all IPs;
• Permissions - which functions the key may call. Each API function has its own permission (for example clients_add, licenses_edit, search);
• Status - the key must be active.

Request Format

Send an HTTP POST request to the central API entry point:

https://www.yourdomain.com/apl_api/api.php

Every request requires these common parameters:

Fields marked by * are required. The api_post_key, referer and User-Agent checks are added automatically by the /apl_api/api.php proxy itself - you only need to submit the parameters above.

Response Format

Every API call returns a JSON-encoded object:

{
    "api_action_success": 1,
    "api_error_detected": 0,
    "action_success": 1,
    "error_detected": 0,
    "page_message": "Client John Doe (john@example.com) added."
}

Response keys:

Endpoints

All endpoints are called through the proxy /apl_api/api.php with api_function set to the endpoint name.

clients_add, clients_edit

licenses_add, licenses_edit

products_add, products_edit

installations_edit

banned_hosts_add, banned_hosts_edit

Search

The search endpoint searches across all record types. Unlike the other endpoints, page_message contains an array of matching records (each record is itself an associative array). When no results are found, the API returns an action_success of 0 with the error message No results found.

Parameters

Note: for security reasons, the search results strip sensitive fields (such as client names and emails for license/installation record types, and admin account IDs for reports).

Examples

Add a client

curl -X POST https://www.yourdomain.com/apl_api/api.php \
  -d "api_key_secret=YOUR_API_KEY_SECRET" \
  -d "api_function=clients_add" \
  -d "submit_ok=Submit" \
  -d "client_fname=John" \
  -d "client_lname=Doe" \
  -d "client_email=john@example.com" \
  -d "client_status=1"

{"api_action_success":1,"api_error_detected":0,"action_success":1,"error_detected":0,"page_message":"Client John Doe (john@example.com) added."}

Add an anonymous (code-based) license

curl -X POST https://www.yourdomain.com/apl_api/api.php \
  -d "api_key_secret=YOUR_API_KEY_SECRET" \
  -d "api_function=licenses_add" \
  -d "submit_ok=Submit" \
  -d "product_id=1" \
  -d "license_code=ABC123XYZ" \
  -d "license_require_domain=0" \
  -d "license_status=1" \
  -d "license_limit=3" \
  -d "license_expire_date=2027-01-01" \
  -d "license_updates_date=2027-01-01" \
  -d "license_support_date=2027-01-01"

Search for a license

curl -X POST https://www.yourdomain.com/apl_api/api.php \
  -d "api_key_secret=YOUR_API_KEY_SECRET" \
  -d "api_function=search" \
  -d "submit_ok=Submit" \
  -d "search_type=license" \
  -d "search_keyword=ABC123"

PHP example

//example API call using cURL in PHP
$api_url="https://www.yourdomain.com/apl_api/api.php";
$post_data=array(
    "api_key_secret"=>"YOUR_API_KEY_SECRET",
    "api_function"=>"clients_add",
    "submit_ok"=>"Submit",
    "client_fname"=>"Jane",
    "client_lname"=>"Smith",
    "client_email"=>"jane@example.com",
    "client_status"=>1
    );

$ch=curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post_data));
curl_setopt($ch, CURLOPT_USERAGENT, "LicenTra Custom Post"); //API only accepts automated user agents
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response=curl_exec($ch);
curl_close($ch);

$result_array=json_decode($response, true);
if (!empty($result_array['action_success'])) //operation succeeded
    {
    echo $result_array['page_message'];
    }
else
    {
    echo "Error: " . $result_array['page_message'];
    }