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'];
}