Products in Commerce can generate license keys. A simple HTTP-based API is available to interact with license keys.
Basics
For each of the endpoints, you will send a HTTP POST request, and a JSON object will be returned. The URL you will be posting to is:
http://www.example.com/applications/nexus/interface/licenses/?ENDPOINT
...where example.com is your own URL, and ENDPOINT is one of the calls listed below.
Configuration
Before you can use the API, you must define some settings. In the root directory of your community, create a constants.php file if you don't already have one (be sure to start the file with <?php) and add this line:
define('NEXUS_LKEY_API_DISABLE', FALSE);
The license key API is disabled by default, and this line enables it. There are two other relevant constants too:
-
NEXUS_LKEY_API_CHECK_IP
Controls whether the IP address of the server making the request needs to be the same when checking or updating data as when the key was activated. Defaults to TRUE. -
NEXUS_LKEY_API_ALLOW_IP_OVERRIDE
Controls whether you can specify an "ip" parameter for this check, overriding what IP actually sent the request. Defaults to FALSE.
Important concepts
There are two important concepts to understand before getting started with the license key API:
- License keys may be able to be used multiple times (you can set how many times when creating your product). When a license key is activated it is assigned a usage ID for that activation which refers to that usage. You will need to log and send this even if you only allow 1 usage.
-
License keys can be given an identifier which is sort of like a password. If a key has an identifier, you will need to send it with all requests. It is strongly recommended you do this, as otherwise someone could brute force the API to get a list of all your license keys. For example, you might use the customer's email address as an identifier and if you do this, the API will only respond to requests which include a valid license key and the correct email. An identifier can be information about the customer, or any custom fields on the product and can be set in your product settings.
Endpoints
This section covers the available endpoints and the data they return.
Call this to activate a license key, for example when a user first enters their key into your application.
Request Parameters
-
key
The license key -
identifier
The identifier (see 'important concepts', above) -
setIdentifier
If "1", and the license key does not currently have a value for its identifier, the provided identifier will be set - if it has already been set and the provided value is not the same, an error will be raised -
extra
JSON-encoded additional data to note. This should be a simple object with key/value pairs where both the keys and values are strings. You will be able to view the data in the Admin CP when viewing the purchase the license key is associated with.
Response Object
-
response
"OKAY" -
usage_id
The usage ID that has been assigned. Be sure to save this in your application; it will be required for future calls (see 'important concepts', above)
Error Codes (in addition to standard errors thrown by the API)
-
201 (MAX_USES)
The key has already been activated the maximum number of times and cannot be activated again.
Call this to check a license key is still active. Must be from the same IP address that called activate was unless overridden by configuration.
Request Parameters
-
key
The license key -
identifier
The identifier associated with this license key (see 'important concepts', above) -
usage_id
The unique usage ID for this license key (see 'important concepts', above)
Response Object
-
status
One of the following values:- ACTIVE - The license key is active
- INACTIVE - The license key, or purchase associated with the license key, has been deactivated.
- EXPIRED - The purchase associated with the license key has expired.
-
uses
The number of times this license key has been activated. Only provided if "STATUS" is "ACTIVE". -
max_uses
The maximum number of times this license key can been activated. Only provided if "STATUS" is "ACTIVE".
Error Codes (in addition to standard errors thrown by the API)
-
303 (BAD_USAGE_ID)
The usage ID provided is invalid. -
304 (BAD_IP)
The IP address making the request does not match the one used to activate the license key.
Call this to get information about a key, not specific to any usage ID.
Request Parameters
-
key
The license key -
identifier
The identifier associated with this license key (see 'important concepts', above)
Response Object
-
key
The license key -
identifier
The identifier associated with this license key -
generated
A unix timestamp of the date that the key was generated. -
expires
A unix timestamp of the date that the purchase the key is associated with will expire. -
usage_data
A multi-dimensional array containing information about the license key's "uses". The array keys are the usage IDs and the value is an array with the following elements:-
activated
A unix timestamp of when this usage was activated. -
ip
The IP address that activated this usage. -
last_checked
A unix timestamp of the date the last "check" API call was received for this usage. -
extra
Additional information as provided to the "activate" API method.
-
activated
-
purchase_id
The ID number of the purchase associated with the license key. -
purchase_name
The name of the purchase associated with the license key. -
purchase_pkg
The ID number of the package in the store of the purchase associated with the license key. -
purchase_active
A boolean value indicating if the purchase associated with the license key is active. -
purchase_start
A unix timestamp of the date that the purchase associated with the license key was purchased. -
purchase_expire
A unix timestamp of the date that the purchase associated with the license key will expire. -
purchase_children
An array containing child purchases of the purchase associated with the license key. The values will be an array of data about the child purchase with the following elements:-
id
The ID number of the purchase. -
name
The name of the purchase. -
app
The application key that the purchases was made from (will be "nexus" for purchases from the store). -
type
The type of purchase (e.g. "product", "hosting", "ad", etc.). -
item_id
The ID number of the package in the store of the purchase. -
active
A boolean value indicating if the purchase is active. -
start
A unix timestamp of the date that the purchase was purchased. -
expire
A unix timestamp of the date that the purchase will expire. -
lkey
The license key associated with the purchase, if it has it's own license key.
-
id
-
customer_name
The customer's name. -
customer_email
The customer's email address. -
uses
The number of times this license key has been used. -
max_uses
The maximum number of times this license key can be used.
Error Codes (in addition to standard errors thrown by the API)
There are no errors thrown by this endpoint other than the standard ones.
Call this to update the "extra" information for a key that was originally sent in the "activate" request. Must be from the same IP address that activate was unless overridden by configuration.
Request Parameters
-
key
The license key -
identifier
The identifier associated with this license key -
usage_id
The unique usage ID associated with this license key -
extra
JSON-encoded new 'extra' data
Response Object
-
status
"OKAY"
Error Codes (in addition to standard errors thrown by the API)
-
303 (BAD_USAGE_ID)
The usage ID provided is invalid. -
304 (BAD_IP)
The IP address making the request does not match the one used to activate the license key.
Report Document