License API

Note

The license API is reserved for customers who were accepted into the reseller partner program.

The reseller program was deprecated in 2019. This documentation is available for customers who were grandfathered into the program, prior to that date.

Introduction

The InterWorx License API can be used to manage InterWorx licenses for authorized resellers. 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. You must also be an authorized reseller with an account that is in good standing. An up-to-date credit card must be 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'];
}