Activation API V1 Reference

Oveview

The Activation API method uses HTTPS POST commands with JSON encoded parameters to implement the software_DNA licensing solution and requires no DNA Library to be installed on the User’s device.

All HTTPS Requests and Responses are signed to ensure secure communication with the DNA Servers.

The <SIGNATURE> is a HMAC256 Hash (Base64 encoded) of several parameters included in the HTTPS Request or Response using the Activation API Key (WEB_KEY) assigned to the DNA Product. The <SIGNATURE> is created by the sender, and re-created by the receiver to validate the signature of the communication.

The <SIGNATURE> is also used by the App to validate the stored DNA License JSON String in the App.

You can retrieve and change the Activation API Key (the WEB_KEY) for your DNA Product from the DNA Control Panel Product Configuration screen. The Key must be kept secret and is not communicated in the communication with the DNA Servers, but used at either end to sign and validate the signature of each communication.

The Activation API Reference provides details on each of the Activation API Calls supported by software_DNA.

All the Activation V1 API’s will return a similar JSON-based Response containing the updated DNA_Key(s) and key information about the License Activation Code that can be extracted and used by the Application.

To complete your licensing implementation when using the Activation API process, you will need to implement in your Device App or Web App some key functions such as read / write of the DNA License and HMAC256 SIGNATURE creation and validation. See Getting Started for details.

DNA License example in JSON format

            
             
            {
                
                "DNA_KEY1":"2044095b-6fa7-11ea-8949-000d3a126e14",
                "DNA_KEY2":"2044095b-6fa7-11ea-8949-000d3a126e14",
                "ACTIVATION_CODE":"XX12345",
                "EMAIL":"info@softworkz.com",
                "EXPIRY_DATE":"4/9/2020",
                "ACTIVATION_DATE":"3/25/2020 4:34:05 PM",
                "SERVER_ACTIVATION_DATE":"3/25/2020 4:34:05 PM",
                "COMPUTER_NAME":"MAC-Chrome",
                "PLATFORM":"O",
                "CLIENT_VERSION":"6.0.0",
                "SERVER_VERSION":"6.0.0",
                "PROTECTION_LEVEL":"3",
                "VALIDATION_WARNING":"4/20/2020",
                "VALIDATION_LIMIT":"4/25/2020",
                "MACHINE_ID":"2044095b6fa711ea8949000d3a126e14",
                "DEVICE_ID":"8c9c72719398508b",
                "LANGUAGE":"EN",
                "ERROR":"0",
                "RESPDATE":"2020-3-30 10:1:39",
                "SIGNATURE":"B8169WRspWL9SjtYHEv4QdC5HVzniZKo0FuGgpge9ow="
                
            }       
 			
            

Issuing a Activation API POST Request

For each Activation API call:

• retrieve the DNA_Key(s) stored on the device / browser to include in the request

• calculate the Request SIGNATURE

• issue the HTTPS POST Request with JSON-based parameters in the request body

• retrieve the HTTPS POST Response in JSON format

• validate the SIGNATURE of the POST Response

• extract and save the updated DNA License on the device / browser

• respond to the ERROR returned

Request example in JSON format

            
             
            {
                "API": "WEB_ACTIVATE_SAAS", 
                "PRODUCT_ID": "P0002964", 
                "ACTIVATION_CODE": "CB12345", 
                "PASSWORD":"********", 
                "EMAIL": "info@softworkz.com", 
                "DNA_KEY1": "", 
                "DNA_KEY2": "", 
                "USERAGENT": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.122 Safari/537.36", 
                "DATE": "4/13/2020 3:07:57 PM",
                "SIGNATURE": "eD9S9vqX7qFhpddJvQeLwRxfwHYByv5;fAMwb0LEnDE=" 
            }
			
            

Using Helper Functions or Web API’s directly

For selected coding environments, we provide "As Is" a set of Helper Functions to simplify the implementation.
See Helper Functions     for details.

The following functions are all you need to know to implement software_DNA:

• DNASetProperties(prop_name, prop_value)
  • configuration settings for the Helper Functions (ex: cdmPathName)
  • must be called before any other Web API calls
• doWebAPI(apiName, ... )
  • issues the HTTPS POST for the specified Web API call
  • generates Request Signatures and validates Response Signatures
  • manages the Web License
  • for WEB_Validate, implements a Local Validation function
• DNAParam(parmName)
  • returns the parmValue of the specified parmName
• DNAError(dnaError)
  • provides a text description of the specifieddnaError error code
• doWebInfoTag(productid, licenseCode, infoTag)
  • sets the infoTag for the License Code
  • maximum length of infoTag is 512 characters and will be encoded in Base64 by this function