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'    => 'you@yourdomain.com',
                   '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'    => 'you@yourdomain.com',
                 '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'    => 'you@yourdomain.com',
                 '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'    => 'you@yourdomain.com',
                 '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'    => 'you@yourdomain.com',
                 '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'    => 'you@yourdomain.com',
                 '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'    => 'you@yourdomain.com',
                 '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'    => 'you@yourdomain.com',
                 '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'];
   }