Integrate license key activations to your premium software application


Introduction

The download key (license) activation feature, if enabled in your UpdaterCloud product details, allows a download key to be used for product updates only after it has been activated on your customer's website. Activations are bound to your customer's website domain name (where your product is installed), so no matter if your customer server IP or MAC address changes over time (for example if your customer changes the hosting provider), an existing download key activation won't be affected. The exception is when your customer's domain name can't be determined, case in which the activation will be bound to the customer's IP address or domain name.

{warning} The download key activation feature is only available for products that use the UpdaterCloud License Manager.

Depending on the download key activations limit, your customer may or may not be able to use the download key to request updates from some other website too. For example, if the download key activations limit is set to 1, then once the download key has been activated and bound to the first website domain, that download key can't be used on some other website to download product updates.

Activate download key

To integrate download key activation in your product, first you need to make a GET request from your product to your public UpdaterCloud Download Key Activation API endpoint and provide your customer download key and product id.

{warning} Make sure to replace the {{SUBDOMAIN}} with your personal UpdaterCloud subdomain, the {{PRODUCT_ID}} with your UpdaterCloud product id and the {{DOWNLOAD_KEY}} with your customer's download key that you're trying to activate.

// Initialize the CURL session
$ch = curl_init();

// Set options for CURL transfer
curl_setopt_array($ch, array(
    CURLOPT_URL => "https://@{{SUBDOMAIN}}.updatercloud.com/api/v1/products/@{{PRODUCT_ID}}/download-keys/activate?download_key=@{{DOWNLOAD_KEY}}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
        "Accept: application/json"
    ),
));

// Perform the CURL request
$response = @curl_exec($ch);

// Close the CURL session and free all resources
curl_close($ch);

// Parse the response with warnings supressed
$body = @json_decode($response);

Sample success response (status code 201)

If the request was successfull, you'll get a 201 Created response and you'll need to save the activation id somewhere in your product database for later use. The activation id will be required later if, for example, your customer will want to deactivate a download key (to activate it on some other website/domain).

{
    "id": "8fce54c8-5ca3-426d-b129-ff550c64e7a2",
    "download_key": "X4F9Q-FK2XW-QATHJ-K9JXY-6TVX8",
    "expires_at": "2021-02-08 12:04:44",
    "product_id": "8fa6e6ec-6941-46b9-87df-7854a685b8d1",
    "domain": "example.com",
    "created_at": "2020-02-08 12:04:44",
    "message": "Download key activated for domain example.com."
}

Sample error responses (status code other than 200 or 201)

If you haven't enabled the download key activation feature in your product, you'll get a 403 Forbidden response and the download key will not be activated.

{
    "error": "Download key activation is not enabled for this product."
}

If the download key has already been activated for the requesting domain, you'll get a 403 Forbidden response and the download key will not be activated again.

{
    "error": "Download key is already activated for My Awesome Product on domain example.com."
}

Id the download key activation limit has been reached, you'll get a 403 Forbidden response and the download key will not be activated.

{
    "error": "Download key activation limit exceeded."
}

The Download Key Activation public API endpoint is rate limited to a maximum of 15 requests per minute from the same IP. If you've reached this limit, you'll get a 429 Too Many Requests response and need to wait 60 seconds before making any new requests to this endpoint.

{
    "message": "Too Many Attempts."
}

Deactivate download key

To deactivate a download key activation, you need to make a GET request to the Deactivate Download Key API endpoint and provide the product id, download key and download key activation id (which you've saved when activating the download key).

{warning} Make sure to replace the {{SUBDOMAIN}} with your personal UpdaterCloud subdomain, the {{PRODUCT_ID}} with your UpdaterCloud product id, the {{DOWNLOAD_KEY}} with your customer's download key and the {{DOWNLOAD_KEY_ACTIVATION_ID}} with the id received when activating the download key.

// Initialize the CURL session
$ch = curl_init();

// Set options for CURL transfer
curl_setopt_array($ch, array(
  CURLOPT_URL => "https://@{{SUBDOMAIN}}.updatercloud.com/api/v1/products/@{{PRODUCT_ID}}/download-keys/deactivate?download_key=@{{DOWNLOAD_KEY}}&download_key_activation_id=@{{DOWNLOAD_KEY_ACTIVATION_ID}}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 10,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Accept: application/json"
  ),
));

// Perform the CURL request
$response = @curl_exec($ch);

// Close the CURL session and free all resources
curl_close($ch);

// Parse the response with warnings supressed
$body = @json_decode($response);

Sample success response (status code 200)

If the request was successfull, you'll get a 200 OK response. The download key has been deactivated for the requesting domain/hostname and can't be used for downloading updates anymore until activated again.

{
    "message": "Download key deactivated."
}

Sample error response (other status code than 200)

If the download key activation id is invalid, you'll get a 404 Not Found response:

{
    "error": "Download key activation id is invalid."
}

Get all download keys activations

Sometimes, depending on the download key activations limit, your customers may want to deactivate a download key so they can activate it again on a new domain. For this, you need to make a GET request from your product to the List Download Key Activations plublic API endpoint.

{warning} Make sure to replace the {{SUBDOMAIN}} with your personal UpdaterCloud subdomain, the {{PRODUCT_ID}} with your UpdaterCloud product id and the {{DOWNLOAD_KEY}} with your customer's download key that you're trying to list activations for.

// Initialize the CURL session
$ch = curl_init();

// Set options for CURL transfer
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://@{{SUBDOMAIN}}.updatercloud.com/api/v1/products/@{{PRODUCT_ID}}/download-keys/activations?download_key=@{{DOWNLOAD_KEY}}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 10,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Accept: application/json"
  ),
));

// Perform the CURL request
$response = @curl_exec($ch);

// Close the CURL session and free all resources
curl_close($ch);

// Parse the response with warnings supressed
$body = @json_decode($response);

Sample success response

If the request was successfull, you'll get a 200 OK response with a list of activations:

{
    "download_key": "X4F9Q-FK2XW-QATHJ-K9JXY-6TVX8",
    "product_id": "8fa6e6ec-6941-46b9-87df-7854a685b8d1",
    "expires_at": "2020-01-12 11:05:22"
    "activations": [
        {
            "id": "8fce54c8-5ca3-426d-b129-ff550c64e7a2",
            "domain": "example.com",
            "created_at": "2020-02-08 12:04:44"
        }
    ]
}

Once you have the activations list, you can build urls to download key deactivation, so you customer can click on them to perform the required deactivations.

Sample error response

If you haven't enabled the download key activation feature in your product, you'll get a 403 Forbidden response.

{
    "error": "Download key activation is not enabled for this product."
}