Assigning Keys To A Domain Name

If your app is a web app, or is installed on a live webserver, or runs as part of a website, like a plugin or a theme, it should send the following data to the API:

1. License key
2. Your unique API Auth Key (shown in your Dashboard)
3. Domain

In this section we discuss how to collect and send the domain for checking. Before we get into how to collect the domain let’s explain the feature in detail.

Domain Locks #

Domains are used to uniquely identify an installation of your app. Keys intended for use on a live webserver are domain locked to prevent unauthorized use of your keys. Without a domain lock, an end user could install your app on an unlimited amount of websites with a single key.

If allowing end users to install your app on unlimited domains is your intended purpose you still must send the domain to the API for the license key check to validate. By setting the maximum amount of domains a key can be used on to 0 (unlimited) the key can still be used on any domain.

NOTE: You must send a domain (or UUID for device installed apps) or the key will not validate.

Available Options #

A key can be locked to the initial domain that sent the key or set to allow X amount of domains. For example, you could sell your app in three tiers that allows it to be installed on a single domain for the silver plan, three domains for the gold plan, and unlimited domains for the platinum plan. It’s an easy way to increase the value of your product with minimum effort.

The amount of domains a key is locked to can be any amount and is up to you. It is set during key generation and can also be changed later in the Dashboard.

Setting the amount of domains a key can be used on to 0 marks it for unlimited use. The key will still record the domains it is installed on, but it will not restrict the key based on domains.

For information on how to make these changes in the Dashboard, as well as edit the actual domains, see our full documentation on the Dashboard.

NOTE: If a previously used unlimited key is later set to domain lock based on the number of domains, ensure this number matches or is larger than the amount of domains already saved to that key.

How Domain Locking Is Checked #

Initial Key Checks: During the initial key check the API will save the domain along with the key and associate the two.

Subsequent Key Checks On Same Domain: Whenever your app rechecks a key the API will compare the requesting domain to the recorded domains and either pass as valid if a match is found or fail if they do not.

Subsequent Key Checks On Different Domains: If an end user installs your app on another domain and enters the same key our system will check if that key allows multiple domains, and if the current amount of domains is within the maximum amount of domains allowed (or unlimited domains are allowed). If so, our system will add the new domain to the key register. If their key only allows one domain or the maximum amount of domains is already associated with that key it will fail to validate the key check.

This means your users can uninstall and reinstall your app as much as they need without contacting you for a key reset, assuming they always install it back on the same domain.

Sending API Calls With A Domain #

Whenever you send an API call be sure to include the domain inside the request headers. We recommend automatically capturing the domain to avoid user error.

Our API expects a variable “domain” as part of the request headers. Here is an example in PHP using cURL of how to collect the domain automatically and send it along with the key. For more information, see our documentation on making API calls.

PHP: #

... rest of code

// Get the domain name
$domain = isset($_SERVER['HTTP_HOST']) ? $_SERVER['HTTP_HOST'] : 'unknown';

// Set cURL options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string instead of outputting it
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); // Enable SSL verification for security

// Set data in the request headers
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
   'auth: ' . $authKey, // Set your unique API authorization key in the request headers
   'key: ' . $licenseKey, // Set the license key in the request headers
   'domain: ' . $domain, // Set the domain in the request headers
));

... rest of code

The above PHP code collects the domain using $_SERVER['HTTP_HOST']. However, you are not limited to only PHP. Any language that has a function similar to $_SERVER['HTTP_HOST'] can be used. Here are a few example for collecting the domain in various popular languages.

Node.js (Express Framework) #

In Node.js, especially when using the Express framework, you can access the host name from the request headers (which includes the domain name) from the request object:

app.get('/api/endpoint', (req, res) => {
    const serverDomain = req.headers.host;
    // Use serverDomain as needed
});

Python (Django Framework) #

In Django, you can use the request.get_host() method to obtain the domain name from the HttpRequest object in view functions, extracting the host information from the request’s Host HTTP header.

from django.http import HttpResponse

def my_view(request):
    # Get the host/domain name
    server_domain = request.get_host()
    # Use server_domain as needed
    
    return HttpResponse("Domain: " + server_domain)

Python (Flask Framework) #

With Flask, another popular web framework for Python, you can get the domain name from the request context:

from flask import request

@app.route('/api/endpoint', methods=['GET'])
def api_endpoint():
    server_domain = request.host
    # Use server_domain as needed

Ruby on Rails #

In Ruby on Rails, you can access the domain name from the request object:

def api_endpoint
    server_domain = request.host
    # Use server_domain as needed
end

.NET Core (C#) #

In .NET Core, you can access the host information from the HttpContext in your controller:

public IActionResult ApiEndpoint() {
    var serverDomain = HttpContext.Request.Host.Value;
    // Use serverDomain as needed
    return Ok();
}

Java (Spring Framework) #

In Spring, you can access the HttpServletRequest object to get the server name:

import javax.servlet.http.HttpServletRequest;

// Inside your controller method
public String apiEndpoint(HttpServletRequest request) {
    String serverDomain = request.getServerName();
    // Use serverDomain as needed
    return "response";
}

Go (using the net/http package) #

In Go, when handling an HTTP request, you can parse the host from the request object:

func apiEndpoint(w http.ResponseWriter, r *http.Request) {
    serverDomain := r.Host
    // Use serverDomain as needed
}

As you can see there is a myriad of options for collecting the domain in all major programming languages.