License API¶
Introduction¶
The InterWorx License API can be used to manage your InterWorx licenses. Both SOAP and XmlRpc API interfaces are available. . A valid e-mail address and password for the InterWorx billing system at https://portal.interworx.com is required to login to the License API. Your account must be in good standing, and you must have an up-to-date credit card on file to order new licenses.
WSDL Location (SOAP)¶
The WSDL Schema is exposed at: https://license-api.interworx.com:2443/soap?wsdl
XmlRpc Point of Contact¶
The XmlRpc access url is: https://license-api.interworx.com:2443/xmlrpc
Web-based License Management Interface¶
A web-based interface to the API functions is also available at https://license-api.interworx.com:2443/nodeworx
API Documentation and Examples¶
/*
* Use your https://portal.interworx.com login and password to authenticate
* via the API
*/
$key = array( 'email' => '[email protected]',
'password' => 'billingpassword' );
/*
* Alternately, you can provide an active SESSION_ID
*
* You can retrieve the session id by using the email / password
* method and then calling the getSession action on the NodeWorx Index
* controller.
*/
$key = array( 'sessionid' => '3c8ae9d982edd507428d8fdd53855a77' );
/*
* All requests to the license API should be sent using the /nodeworx/license/api
* controller
*/
$api_controller = '/nodeworx/license/api';
/*
* You then specify an action you wish to perform.
* The following actions are currently available.
* order
* bulkOrder
* cancel
* bulkCancel
* changeIP
* queryLicenses
* queryLicenseCount
* listPackagesAvailableForPurchase
*/
/* Here is an exmaple using listPackagesAvailableForPurchase */
$action = 'listPackagesAvailableForPurchase';
$input = array();
$params = array( 'apikey' => $key,
'ctrl_name' => $api_controller,
'action' => $action,
'input' => $input );
// You can connect using XMLRPC, like this:
// NOTE: This example makes use of the Zend Framework's XMLRPC library.
$client = new Zend_XmlRpc_Client( 'https://license-api.interworx.com:2443/xmlrpc' );
$result = $client->call( 'iworx.route', $params );
// Or, you can use SOAP, like this:
// NOTE: if SOAP is missing, try 'yum install php-soap'
$client = new SoapClient( 'https://license-api.interworx.com:2443/soap?wsdl' );
$result = $client->route( $key, $api_controller, $action, $input );
if( $result['status'] == 0 ) {
// success
print_r( $result['payload'] );
} else {
// failure
print( 'Error: ' . $result['payload'] );
}
The above example will print out the types of licenses your account is allowed to purchase, for example:
Array
(
[0] => Array
(
[value] => leased_1
[display] => InterWorx-CP License (Leased) $XX.XX Monthly
)
[1] => Array
(
[value] => leased_3
[display] => InterWorx-CP License (Leased) $XX.XX Quarterly
)
[2] => Array
(
[value] => leased_6
[display] => InterWorx-CP License (Leased) $XXX.XX Semi Annually
)
[3] => Array
(
[value] => leased_12
[display] => InterWorx-CP License (Leased) $XXX.XX Annually
)
[4] => Array
(
[value] => owned_1
[display] => InterWorx-CP License (One-Time) $XXX.XX One-Time-Do-Not-Renew
)
)
API Action: order¶
Using the above information, I could then place an order for one InterWorx license, billed monthly, like this:
$key = array( 'email' => '[email protected]',
'password' => 'billingpassword' );
$api_controller = '/nodeworx/license/api';
$action = 'order';
$input = array( 'license_type' => 'leased_1' );
$params = array( 'apikey' => $key,
'ctrl_name' => $api_controller,
'action' => $action,
'input' => $input );
$client = new SoapClient( 'https://license-api.interworx.com:2443/soap?wsdl' );
$result = $client->route( $key, $api_controller, $action, $input );
if( $result['status'] == 0 ) {
echo $result['payload']; // prints "1 license ordered \nLICENSE_KEY_HERE"
} else {
echo 'Error: ' . $result['payload'];
}
API Action: bulkOrder¶
Here’s an example using bulkOrder.
$key = array( 'email' => '[email protected]',
'password' => 'billingpassword' );
$api_controller = '/nodeworx/license/api';
$action = 'bulkOrder';
// order 5 licenses leased monthly, and 3 "one time" owned licenses.
$input = array( 'quantity_leased_1' => 5,
'quantity_owned_1' => 3 );
$params = array( 'apikey' => $key,
'ctrl_name' => $api_controller,
'action' => $action,
'input' => $input );
$client = new SoapClient( 'https://license-api.interworx.com:2443/soap?wsdl' );
$result = $client->route( $key, $api_controller, $action, $input );
if( $result['status'] == 0 ) {
echo $result['payload'];
// prints "8 licenses ordered \nLICENSE_KEY_HERE\nLICENSE_KEY2_HERE...etc"
} else {
echo 'Error: ' . $result['payload'];
}
API Action: cancel¶
Here’s how to cancel a license:
$key = array( 'email' => '[email protected]',
'password' => 'billingpassword' );
$api_controller = '/nodeworx/license/api';
$action = 'cancel';
$input = array( 'license_key' => 'INTERWORX_XXXXXXXXX' );
$params = array( 'apikey' => $key,
'ctrl_name' => $api_controller,
'action' => $action,
'input' => $input );
$client = new SoapClient( 'https://license-api.interworx.com:2443/soap?wsdl' );
$result = $client->route( $key, $api_controller, $action, $input );
if( $result['status'] == 0 ) {
echo $result['payload']; // prints "1 license canceled"
} else {
echo 'Error: ' . $result['payload'];
}
API Action: bulkCancel¶
Here’s how to cancel more than one license at a time:
$key = array( 'email' => '[email protected]',
'password' => 'billingpassword' );
$api_controller = '/nodeworx/license/api';
$action = 'bulkCancel';
$input = array( 'license_key' => array( 'INTERWORX_XXX1', 'INTERWORX_XXX2', 'etc' );
$params = array( 'apikey' => $key,
'ctrl_name' => $api_controller,
'action' => $action,
'input' => $input );
$client = new SoapClient( 'https://license-api.interworx.com:2443/soap?wsdl' );
$result = $client->route( $key, $api_controller, $action, $input );
if( $result['status'] == 0 ) {
echo $result['payload']; // prints "X licenses canceled"
} else {
echo 'Error: ' . $result['payload'];
}
API Action: changeIP¶
You can also use the API to change the IP bound to a license. Note that you do not need to do this for new licenses, only licenses that have already been bound to a server already at activation.
$key = array( 'email' => '[email protected]',
'password' => 'billingpassword' );
$api_controller = '/nodeworx/license/api';
$action = 'changeIP';
$input = array( 'license_key' => 'INTERWORX_XXXXXXXXX',
'ip' => '123.123.123.123' );
$params = array( 'apikey' => $key,
'ctrl_name' => $api_controller,
'action' => $action,
'input' => $input );
$client = new SoapClient( 'https://license-api.interworx.com:2443/soap?wsdl' );
$result = $client->route( $key, $api_controller, $action, $input );
if( $result['status'] == 0 ) {
echo $result['payload']; // prints "License IP changed"
} else {
echo 'Error: ' . $result['payload'];
}
API Action: queryLicenses¶
You can also query licenses under your account.
$key = array( 'email' => '[email protected]',
'password' => 'billingpassword' );
$api_controller = '/nodeworx/license/api';
$action = 'queryLicenses';
// The default behavior, with no input, will return ALL licenses,
// including 'active', 'suspended', and 'canceled' linceses.
$input = array();
// You can query only active licenses like this
$input = array( 'status' => array( 'active' ) );
// You can query only leased licenses like this
$input = array( 'license_type' => array( 'leased' ) );
// 'owned' is another posibility here.
// You can also use this action to query for a specific license, like this
$input = array( 'key' => 'INTERWORX_XXXXXXXXX' );
// You can also query based on the IP address the licenses is bound to
$input = array( 'ip' => '123.123.123.123' );
$params = array( 'apikey' => $key,
'ctrl_name' => $api_controller,
'action' => $action,
'input' => $input );
$client = new SoapClient( 'https://license-api.interworx.com:2443/soap?wsdl' );
$result = $client->route( $key, $api_controller, $action, $input );
if( $result['status'] == 0 ) {
print_r $result['payload'];
} else {
echo 'Error: ' . $result['payload'];
}
The result for one license would look like this:
Array
(
[0] => Array
(
[license_key] => INTERWORX_XXXXXXXXX
[package_name] => InterWorx-CP License (Leased)
[status] => active
[billing_cycle] => Monthly
[start_date] => 2009-10-08
[next_renew_date] => 2010-01-01
[renewed_on] => 2009-12-1
[ip] => 123.123.123.123
[last_checkin] => 2009-12-15 15:41:02
[license_status] => active
)
API Action: queryLicenseCount¶
Finally, there is the queryLicenseCount action, which takes the same parameters with the same defaults as queryLicense, but just returns the number of licenses that match the query.
$key = array( 'email' => '[email protected]',
'password' => 'billingpassword' );
$api_controller = '/nodeworx/license/api';
$action = 'queryLicenseCount';
// The default behavior, with no input, will return ALL licenses,
// including 'active', 'suspended', and 'canceled' linceses.
$input = array();
$params = array( 'apikey' => $key,
'ctrl_name' => $api_controller,
'action' => $action,
'input' => $input );
$client = new SoapClient( 'https://license-api.interworx.com:2443/soap?wsdl' );
$result = $client->route( $key, $api_controller, $action, $input );
if( $result['status'] == 0 ) {
echo $result['payload']; // prints "200" for example
} else {
echo 'Error: ' . $result['payload'];
}