Activating Machines

Use Keygen's API and your code to implement machine activation for your product. If you need help after reading this, can reach out to us anytime at [email protected].

Validation and activation flow

Once you've created a license, you can "activate" individual machines for your product to be used on, making it easier for you to implement a node-locked or floating licensing model. Although Keygen doesn't use the term "activation" much in our resource documentation, machine creation accomplishes the same thing, while machine deletion would be "deactivation."

Implementing a node-locked or node-limited license model consists of 3 to 4 separate steps, each done in a separate API request:

1. Create the license - this is the step where you create the user's license resource, typically done server-side after you've received a payment, or after they've registered for an account with you.
2. Validate their license - this step should be initiated client-side from within your software (e.g. prompt them for a license key after starting your software), and can be performed both before and after activation. Validating before activation so you can be sure the license supports another machine; validating after activation to ensure the newest activation didn't invalidate the license.
3. Activate their machine - this step should be initiated from within your software, so you can have access to the underlying machine to be able to query information such as MAC address, HDD ID, etc. for use in fingerprinting the user's current machine.

Activation requests can either be performed client- or server-side, and depending on which one of those you choose, the tokens you use to make the request will be different i.e. product tokens vs. user tokens vs. activation tokens, for server-side and client-side machine activations.

How to identify a device

When activating a machine (device), you will at minimum need a license ID for the license the activation is for, and a fingerprint for the current device. Other machine attributes, such as name, IP or hostname, are completely optional.

In the example below, we'll be using a SHA256 hash of the current device's native unique identifer as a fingerprint. We're hashing the device ID as a simple way to anonymize it, since we have no real use in knowing its actual value. Using an HMAC digest (i.e. HMAC-SHA256) might be an even better way to anonymize the user's MAC address.

Although we're using a device's unique machine ID in this example, a fingerprint can be any unique string able to be reproducibly queried from the device, e.g. you could write a secure random string to a file on disk or to a registry and use that, but for example purposes the device's ID works well enough.

Using macOS, you can obtain the native device ID (under property IOPlatformUUID) with the following shell command:

ioreg -rd1 -c IOPlatformExpertDevice
ioreg -rd1 -c IOPlatformExpertDevice

What makes up a machine "fingerprint" is up to you. As long as it's a unique value that has a low likelihood of changing, it will work fine. For example, storing a random UUID to disk may be the simplest solution for some products, but that may not work for other products.

A machine can always be deactivated in the event that a device ID changes due to hardware or operating system changes.

How to activate a device

Below is an example of performing a machine activation request.

curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/machines \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer {TOKEN}' \
  -d '{
        "data": {
          "type": "machines",
          "attributes": {
            "fingerprint": "f1adc3aed0ba31a418fc7c2e1d63c3e0b1207a6cea5613f650945235f1812fcd",
            "name": "Office Mac Pro",
            "platform": "macOS"
          },
          "relationships": {
            "license": {
              "data": {
                "type": "licenses",
                "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
              }
            }
          }
        }
      }'
curl -X POST https://api.keygen.sh/v1/accounts/{ACCOUNT}/machines \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer {TOKEN}' \
  -d '{
        "data": {
          "type": "machines",
          "attributes": {
            "fingerprint": "f1adc3aed0ba31a418fc7c2e1d63c3e0b1207a6cea5613f650945235f1812fcd",
            "name": "Office Mac Pro",
            "platform": "macOS"
          },
          "relationships": {
            "license": {
              "data": {
                "type": "licenses",
                "id": "4097d726-6cc5-4156-8575-3a96387e19b4"
              }
            }
          }
        }
      }'

Example applications

Below you can find example applications detailing machine activation in various programming languages. These may be a great place to start.

Next steps

That's that! You've activated your first machine using Keygen. Next up, we could update a license's policy to require a machine fingerprint during validating using the "require fingerprint scope" setting, or adjust the license's maximum machine limit.

If you have any questions about what you've learned today, be sure to reach out!