This document describes the RLM Activation Pro web services API.

The RLM Activation Pro API is described in the sections on the left. To view a section, click on the title on the left-hand side.

Activation Pro API Intro

Activation Pro supports a Web Services API to control most aspects of the Activation Pro database. It is implemented as a simple REST-style service, using JSON to encode the information going to and from the Activation Pro system. The Overview section lists the functions which can be performed
1-jun-2018

API Overview

The Activation Pro API functions live at https://hostedactivation.com/isv/api/function.php The API consists of 18 functions, organized into 5 API groups, as outlined in the following table:

URI	GET	POST	PUT	DELETE	Notes
/api/company.php	lists companies	create new company	edit company info	delete company
/api/contact.php	lists contacts	create new contact	edit contact info	delete contact
/api/akey.php	lists activation keys	create new activation key(s)	edit activation key	delete activation key	delete requires that no fulfillments referencing this key exist
/api/prod.php	list products	create new product(s)	edit product	delete product	delete requires that no activation keys referencing this product exist
/api/fulfillment.php	list fulfillments	---	---	delete fulfillment

All communications with the Acttivation Pro API are done over https: and the messages are encoded in JSON. All functions require a JSON header with a minimum of the following data. If this data is missing, a login error will be returned. Additional data is described in the section for each API group:

field	meaning
user	Activation Pro username
password	md5 password for this username

NOTE: some systems do not allow any data with a GET request. To accomodate this, the JSON header can contain a "method_override" member which tells the Activation Pro API to use this method rather than the one that was specified with HTTP. Add "method_override" to the JSON header and use any HTTP method you chose.

NOTE: For methods that search for data (get, post, delete) the header may contain search terms in the form of "field":"value". There may be multiple of them in a header. The web services form searches by combining multiple search terms with an AND. So for example, a header which contains
"id":"22",
"num":"100"
would search for rows whose id value is 22 AND whose num value is 100.

Each function returns 3 values in the JSON data:

field	meaning
status	Operation Status, "ERROR" or "OK"
code	numeric status code for the operation
message	Operation unique message

POST, PUT, and DELETE operations are logged in the audit trail.

There are some operations which can be done in the Activation Pro GUI (rlc) which cannot be done in the API. This is by design; the following capabilities are not present in the API

• define and run reports
• set up product definition and activation key defaults
• Admin functions such as uploading generator setings files, retrieving the audit trail, setting up blacklists, backing up the database, etc,

Each function is described in detail in the sections which follow.

API Authentication

There are 2 different levels of access control for the Activation Pro web service.

The first level is the webserver login; this data goes into the http headers in the "Authorization:" section (-u option to CURL). These credentials give access to the directory of API functions only.

Here is the CURL command with the first-level authentication for the fictional company Acme:

curl -X get -H "Content-Type: application/json" -H "Accept: application/json" 
     -d @prod.json https://hostedactivation.com/acme/api/company.php -u 'user:password'

The second level is the Activation Pro login username and password, which is unique to you. This is placed in the JSON header which is sent with every Activation Pro API function. Depending on the function to be performed, this login must have the appropriate access. Access requirements are listed in each API section, but in general, GET methods require "view" access and the other methods require "edit" access. The JSON header with the Activation Pro login would look like this (this is the command to list active product definitions for the product "supercompiler", from the example above, this would be in the file "prod.json"):

	{ 
	    "header":
	    {
	        "user":"ActivationPro-username", 	
	        "password":"md5-of-password-here",
	        "active": "1", 
	        "product": "supercompiler" 
	    } 
	}
	

It is important to use a different username for API access and interactive Activation Pro access, otherwise interactive users will interfere with the API calls. If you have multiple processes using the API, they should use separate usernames as well.

API Details - company

Activation Pro API - Company functions

The company functions perform the following operations:

URI	GET	POST	PUT	DELETE
/api/company	lists companies	create new company	edit company info	delete company
Activation Pro access required	view	edit	edit	edit
Success status return	# of company records returned	company ID (message contains IDs of company records created)	0	0

All functions require a JSON header with a minimum of:

field	meaning
user	ActivationPro username
password	md5 password for this username

In addition, the following parameters can be specified:

field	meaning	Required for
method_override	override requested method	---
company_id	company id	put and delete

POST requires a unique company name. All other company data is optional for POST and PUT.
GET can search on zero or more fields. If no fields are specified all company records are returned. Any field supplied is treated as a regular expression (PHP REGEXP). If multiple fields are supplied they are ANDed together for searching. So for example supplying company "fr" will match "Fred" or "Acme Company of France". Supplying that and country "USA" will return only "Fred".

The following example retrieves all companies in Washington state:

	curl -X get -H "Content-Type: application/json" 
		-H "Accept: application/json" -d @company.json 
		https://hostedactivation.com/isv/api/company.php -u 'user:password'
	

and in company.json:

	{ 
	    "header":
	    { 
	        "user":"ActivationPro-user",
	        "password":"md5-password",
	        "state": "wa" 
	    }
	}
	

This command will return data which is similar to this (when printed with a php "print_r" call and reformatted slightly):

      Array ( 
	[0] => stdClass Object ( [status => OK [code] => 2 [message] => 2 rows found )
	[1] => Array (
	  [0] => stdClass Object ( [company_id] => 39  
	  	[company] => performance testing corp
		[addr1] => 123 Main St[addr2] => [addr3] => 
		[city] => Olympia [state] => Wash [zip] => 98502
		[country] => [c_notes] => 
		[u1] => [u2] => [u3] => [u4] => [u5] => [u6] => [u7] => 
		[u8] => [u9] => [u10] =>)
	  [1] => stdClass Object ( [company_id] => 36 
	  	[company] => Wheat Associates
		[addr1] => 19882 Field Rd. [addr2] => [addr3] => 
		[city] => Ritzville [state] => Washington [zip] => 99169
		[country] => [c_notes] => 
		[u1] => [u2] => [u3] => [u4] => [u5] => [u6] => [u7] => 
		[u8] => [u9] => [u10] => )
	) 
     ) 
	

API Details - contact

Activation Pro API - Contact functions

The contact functions perform the following operations:

URI	GET	POST	PUT	DELETE
/api/contact.php	lists contacts	create new contact	edit contact info	delete contact
ActivationPro access required	view	edit	edit	edit
Success status return	# of contact records returned	contact ID (message contains IDs of contact records created)	0	0

All functions require a JSON header with a minimum of:

field	meaning
user	ActivationPro username
password	md5 password for this username

In addition, the following parameters can be specified:

field	meaning	Required for
method_override	override requested method	---
contact_id	contact id	put, post and delete

POST, PUT and DELETE require a contact id. All other contact data is optional for POST and PUT.

The following example retrieves the 1st page of contact entries:

	curl -X get -H "Content-Type: application/json" 
		-H "Accept: application/json" -d @contact.json 
		https://hostedactivation.com/isvapi/contact.php -u 'user:password'
	

and in contact.json:

	{ 
	    "header":
	    { 
	        "user":"ActivationPro-user",
	        "password":"md5-password",
	        "contact": "Malone" 
	    }
	}
	

This command will return data which is similar to this (when printed with a php "print_r" call and reformatted slightly):

      Array ( 
	[0] => stdClass Object ( [status] => OK [code] => 1 [message] => 1 rows found ) 
	[1] => Array (
	  [0] => stdClass Object ( [contact_id] => 44 
	  	[contact] => Pat Malone [contact_type] => [title] => VP Sales
		[phone] => 424-857-2201 [fax] => 
		[email] => patm@tunnel.com [info] => [company_id] => 36 
		[ccreate] => 2017-12-27)
	) 
     ) 
	

API Details - product

ActivationPro API - Product functions

The Product functions perform the following operations:

URI	GET	POST	PUT	DELETE
/api/product.php	lists product definitions	create new product definition	edit product definition	delete product definition
ActivationPro access required	view	edit	edit	edit
Success status return	# of product definitions returned	activation key ID (message contains IDs of akey records created)	0	0

All functions require a JSON header with a minimum of:

field	meaning
user	ActivationPro username
password	md5 password for this username

In addition, the following parameters can be specified:

field	meaning	Required for
method_override	override requested method	---
id	product defintion id	for put and delete

The following example creates a product definition for "testprod" which generates a single "testprod" v1.0 floating license which does not expire:

	curl -X post -H "Content-Type: application/json" 
		-H "Accept: application/json" -d @product.json 
		https://hostedactivation.com/isv/api/product.php -u 'user:password'
	

and in product.json:

	{ 
	    "header":
	    { 
	        "user":"ActivationPro-user",
	        "password":"md5-password",
	        "active": "1",
	        "name": "testprod",
	        "product": "test",
	        "version": "1.0",
		"lictype":"0",
	        "exp": "0",
	        "nlic": "1"
	    }
	}
	

This command will return the following status (when printed with a php "print_r" call and reformatted slightly):

      Array ( 
	[0] => stdClass Object ( [status] => OK [code] => 1 [message] => 1 rows added, product_ids: 112 )
	) 
	

API Details - activation key

Activation Pro API - Activation Key functions

The Activation Key functions perform the following operations:

URI	GET	POST	PUT	DELETE
/api/akey.php	list activation keys	create activation key	edit activation key	delete activation key
ActivationPro access required	view	edit	edit	edit
Success status return	# of activation key records returned	activation key ID (message contains IDs of akey records created)	0	0

All functions require a JSON header with a minimum of:

field	meaning
user	Activation Pro username
password	md5 password for this username

In addition, the following parameters can be specified:

field	meaning	Required for
method_override	override requested method	---
akey	akey	put, delete

For GET requests, any field or combination of fields as detailed in the Activation Pro manual Appendix D may be specified. Multiple values are ANDed together to form search criteria. So for example, a JSON header to specify a search for active keys specifying product definition 510 would be as follows:

        {
            "header":
            {
                "user":"ActivationPro-user",
                "password":"md5-password",
                "active": "1",
		"product_id":"510"
            }
        }
	

All commands return 0 for success, or an error code.



The following example lists all activation keys with product_id 27:

	curl -X get -H "Content-Type: application/json" 
		-H "Accept: application/json" -d @akey.json 
		https://hostedactivation.com/isvapi/akey.php -u 'user:password'
	

and in akey.json:

	{ 
	    "header":
	    { 
	        "user":"ActivationPro-user",
	        "password":"md5-password",
	        "product_id": "27"
	    }
	}
	

API Details - fulfillment

Activation Pro API - Fulfillment functions

The Fulfillment functions perform the following operations:

URI	GET	DELETE
/api/fulfillment.php	list fulfillments	delete fulfillments
ActivationPro access required	view	edit
Success status return	# of fulfillments returned	0

All functions require a JSON header with a minimum of:

field	meaning
user	ActivationPro username
password	md5 password for this username

In addition, the following parameters can be specified:

field	meaning	Required for
method_override	override requested method	---
id	fulfillment ID	delete

The following example lists all fulfillments for activation key 9834-1783-2262-6678:

	curl -X get -H "Content-Type: application/json" 
		-H "Accept: application/json" -d @fulfillment.json 
		https://hostedactivation.com/isv/api/server.php -u 'user:password'
	

and in fulfillment.json:

	{ 
	    "header":
	    { 
	        "user":"ActivationPro-user",
	        "password":"md5-password",
	        "akey": "9834-1783-2262-6678"
	    }
	}
	

This command will return a fulfillment list similar to the following (when printed with a php "print_r" call and reformatted slightly):

      Array ( 
	[0] => stdClass Object ( [status] => OK [code] => 0 [message] => 1 rows found )
	[1] => Array ( 
	  [0] => stdClass Object ( [id] => 178 [akey] => 9834-1783-2262-6678 
	      [product_id] => 98 [count] => 1 [time] => 1505838111 
	      [license_hostid] => 0059a9fc0394 [reference_hostid] => 0 
	      [expdate] => 12-jun-2019 [hostname] => foxhat 
	      [remote_host] => 22.231.38.189 [log] =>
	      [license] => LICENSE reprise test1 1.0 12-jun-2019 uncounted hostid=0059a9fc0394 sig=...
	      [last_fulfill] => 1505838111 [num_fulfills] => 1
	      [revoked] => 0 [revoke_time] => 0 [last_check] => 0
	      [time_str] => 2017-09-26 last_fulfill_str => 2017-09-26
	      [last_check_str] =>