# Integrating License Key Activation

This guide covers software such as desktop apps (macOS or Windows), Chrome extensions, and SaaS products that rely on license key activation.

WordPress Users

If you are integrating Freemius with a WordPress plugin, theme, or add-on, please follow the [WordPress SDK integration guide](https://freemius.com/help/help/documentation/wordpress/integration-with-sdk/.md).

## Initial Steps[​](#initial-steps "Direct link to Initial Steps")

1. [Sign up for Freemius](https://dashboard.freemius.com/register/).
2. Create a new SaaS or App product tailored to your needs.
3. Go to the Plans and [configure the plans and prices](https://freemius.com/help/help/documentation/wordpress/setup-product-pricing-plans-refunds/.md).

For pre-purchase registration, see the [Checkout integration section](https://freemius.com/help/help/documentation/saas/saas-integration/.md#checkout-integration) in the [SaaS Integration doc](https://freemius.com/help/help/documentation/saas/saas-integration/.md).

## Revealing License Keys to Customers[​](#revealing-license-keys-to-customers "Direct link to Revealing License Keys to Customers")

To integrate license key activation, you need to enable the option to show license keys to your customers. This is done in the Freemius Developer Dashboard.

1. Log in to the [developer dashboard](https://dashboard.freemius.com/).
2. Navigate to the **Settings** page.
3. Under the **License Keys** section, toggle on the switch to "show license keys to customers". The setting is automatically saved.
   <!-- -->
   ![Freemius Dashboard License Keys Setting](/help/assets/ideal-img/freemius-dashboard-license-keys-setting.488ec05.480.png)

Depending on your product type, the default behavior is different:

* For [**SaaS**](https://freemius.com/help/help/documentation/saas/saas-integration/.md), license keys are **hidden** by default from your customers. You need to turn the option on.
* For [**Apps**](https://freemius.com/help/help/documentation/saas/app-integration/.md), license keys are **shown** by default to your customers. You don't need to change the settings.

Enabling the option allows customers to view their license keys via their invoices, post-purchase emails, and the customer portal. This is useful for reinstallation or transferring the license to another device.

## Checkout Integration[​](#checkout-integration "Direct link to Checkout Integration")

[Integrate the checkout](https://freemius.com/help/help/documentation/checkout/integration/freemius-checkout-buy-button/.md) with your buy buttons as a modal dialog triggered by JavaScript, or by using direct checkout links.

If you require registration prior to purchasing, check the ***Checkout integration*** section in the [SaaS Integration doc](https://freemius.com/help/help/documentation/saas/saas-integration/.md).

## License Key Integration[​](#license-key-integration "Direct link to License Key Integration")

Create a license form in your app to validate the key.

### License Activation[​](#license-activation "Direct link to License Activation")

To activate a license key, send a `POST` request to the [license activation API endpoint](https://freemius.com/help/help/api/licenses/activate/.md):

```
POST /v1/products/{product_id}/licenses/activate.json

Host: api.freemius.com

Content-Type: application/json



{

  "uid": "{uuid}",

  "license_key": "{license_key}",

  "title": "{title}"

}
```

The following parameters must be included in the request body:

* `{title}` – The name of the installation device. This helps you and [your customer](https://freemius.com/help/help/documentation/users-account-management/activations/.md#activation-details-and-plan-upgrade) identify the device during deactivation. For example, "John's MacBook Pro".
* `{license_key}` – The entered license key
* `{uuid}` – An unique 32-character identifier. You need to generate it from your application. See [below](#generating-a-unique-identifier-uuid) for examples.

You can also include additional parameters which you can find in our [API documentation](https://freemius.com/help/help/api/licenses/activate/.md#licenses/activate/request/body).

#### Generating a Unique Identifier (UUID)[​](#generating-a-unique-identifier-uuid "Direct link to Generating a Unique Identifier (UUID)")

Here are some code snippets to generate a unique identifier (UUID) for different platforms. The UUID should be consistent for the same device, so it can be used to track license activations and deactivations.

* Node.js
* Browser
* Windows
* MacOS

```
import nodeMachineId from 'node-machine-id';

import crypto from 'node:crypto';



// Works for any JS runtime, like Nodejs, Bun, Deno, etc.

function getDeviceGuid() {

  const rawMachineId = nodeMachineId.machineIdSync();



  return crypto

    .createHash('sha256')

    .update(`freemius-my-app:${rawMachineId}`)

    .digest('hex')

    .slice(0, 32);

}



console.log(getDeviceGuid());
```

```
// Store uuid in the local storage where the license is activated.

crypto.randomUUID().replace(/-/g, '');
```

```
// With C# using Microsoft.Win32;

using System.Security.Cryptography;

using System.Text;



string GetDeviceId()

{

    string? machineGuid = null;



    try

    {

        using var key = Registry.LocalMachine.OpenSubKey(@"SOFTWARE\Microsoft\Cryptography");

        machineGuid = key?.GetValue("MachineGuid")?.ToString();

    }

    catch

    {

        // ignore and fallback

    }



    // If MachineGuid exists → hash it

    if (!string.IsNullOrWhiteSpace(machineGuid))

    {

        using var md5 = MD5.Create();

        var bytes = Encoding.UTF8.GetBytes(machineGuid);

        var hash = md5.ComputeHash(bytes);



        return Convert.ToHexString(hash); // 32 chars

    }



    // Fallback → random 32-char ID

    return Guid.NewGuid().ToString("N"); // also 32 chars

}
```

```
import Foundation

import IOKit

import CryptoKit



func getDeviceId() -> String {

  if let uuid = getIOPlatformUUID(), !uuid.isEmpty {

      return md5(uuid)

  }



  // fallback → random 32-char ID

  return UUID().uuidString.replacingOccurrences(of: "-", with: "")



}



private func getIOPlatformUUID() -> String? {

  let matching = IOServiceMatching("IOPlatformExpertDevice")

  let service = IOServiceGetMatchingService(kIOMainPortDefault, matching)



  defer {

      IOObjectRelease(service)

  }



  guard service != 0 else { return nil }



  if let cfUUID = IORegistryEntryCreateCFProperty(

    service,

    "IOPlatformUUID" as CFString,

    kCFAllocatorDefault,

    0

  ) {

      return cfUUID.takeRetainedValue() as? String

  }



  return nil

}



private func md5(_ string: String) -> String {

    let data = Data(string.utf8)

    let digest = Insecure.MD5.hash(data: data)

    return digest.map { String(format: "%02hhx", $0) }.joined().uppercased()

}
```

If the license key is valid and activated, the endpoint will return an object with various useful properties which you can find in the [API documentation](https://freemius.com/help/help/api/licenses/activate/.md#licenses/activate/response\&c=200). The most important properties are:

* `install_id`: The ID of the created `Install` entity. This is essentially the record of the activation for the specific device.
* `install_api_token`: A bearer token that can be used to update the properties of the `Install` entity. More information can be found [here](https://freemius.com/help/help/documentation/saas/app-integration/.md#synchronizing-application-state-with-freemius).
* `license_plan_name`: The name of the plan associated with the activated license key. This is useful for showing the user which plan they are currently subscribed to.
* `license_plan_id`: The ID of the plan associated with the activated license key. This is useful for mapping features to a specific plan.
* `license_pricing_id`: The ID of the pricing associated with the activated license key. This is useful for mapping features to a specific pricing tier (for example usage quotas).

Save the activation details

Ensure to store the `uuid`, `install_id`, `install_api_token` and `license_key` in the local storage (for Chrome extension use [chrome.storage](https://developer.chrome.com/docs/extensions/reference/api/storage)) where the license is activated. You'll need these details during license validation and deactivation.

### License Deactivation[​](#license-deactivation "Direct link to License Deactivation")

To deactivate a license, send a `POST` request to the [license deactivation API endpoint](https://freemius.com/help/help/api/licenses/deactivate/.md):

```
POST /v1/products/{product_id}/licenses/deactivate.json?fields=id%2Cname%2Cslug

Host: api.freemius.com

Content-Type: application/json



{

  "uid": "{uuid}",

  "install_id": "{install_id}",

  "license_key": "{license_key}"

}
```

* `{uuid}` – Must be replaced with the stored install’s uuid
* `{install_id}` – Must be replaced with the stored install’s ID
* `{license_key}` – Must be replaced with the stored license key

### License Validation[​](#license-validation "Direct link to License Validation")

To validate a license, first fetch the activated license with a `GET` request to the [Retrieve an active license by ID API endpoint](https://freemius.com/help/help/api/installations/retrieve-active-license-by-id/.md):

```
GET /v1/products/{product_id}/installs/{install_id}/license.json?uid={uuid}&license_key={license_key}

Host: api.freemius.com
```

* `{uuid}` – Must be replaced with the stored install’s uuid
* `{install_id}` – Must be replaced with the stored install’s ID
* `{license_key}` – Must be replaced with the stored license key

If the license is activated on the specified install, the endpoint returns a `License` object that includes the `expiration` and `is_cancelled` properties (among others).

If `is_cancelled` is `true`, the license was canceled from the Developer Dashboard and is therefore invalid. If the license wasn’t canceled, `expiration` contains the license expiration date formatted as `Y-m-d H:i:s` (it can also be equal to `null` for lifetime licenses).

URL-encode query parameters for GET requests

When sending any query parameter with a `GET` request, for example, the license key or the UUID, please make sure to encode the values. For example:

* PHP
* JavaScript

```
$url = "https://api.freemius.com...?license_key=" . url_encode($license_key);
```

```
const url = `https://api.freemius.com...?license_key=${encodeURIComponent(licenseKey)}`;
```

## Distributing the Software[​](#distributing-the-software "Direct link to Distributing the Software")

After integrating license key activation, the next step is to set up [custom download links](https://freemius.com/help/help/documentation/saas/custom-download-links/.md), where your customers can download the app files.