unlocktopus logo

unlocktopus

JavaScript SDK

Use our JavaScript SDK to easily validate license keys and tokens in your products.

Installation

To install the Unlocktopus JavaScript SDK, you can use npm or yarn:

Installation

npm install unlocktopus-client --save

Usage

To use the Unlocktopus JavaScript SDK, you need to import the UnlocktopusClient class from the SDK and create an instance of it configured with either a license key or license token and the public key. An instance of the client SDK is always bound to a specific product, so you need to provide the product ID as well.

import UnlocktopusClient from 'unlocktopus-client'

const unlocktopus = new UnlocktopusClient({
  // the product ID is always required - grab it from the dashboard
  productId: '[PRODUCT_ID]',

  // if you ask the user to enter their license key, set it here
  licenseKey: '[LICENSE_KEY]',

  // if you're using a license token:
  licenseToken: '[LICENSE_TOKEN]',
  publicKey: '[PUBLIC_KEY]', // you find your product's public key in the dashboard
})

Once you have an instance of the UnlocktopusClient class, you can use it to perform the following actions.

.validate()

Validate

This is a shorthand method that tries to validate the license based on what you configured the SDK with and whether there is a network connection available.

  1. If you provided a license key, it will first attempt to validate it, calling /licenses/validate-key. If the request failed due to a network error, and you also provided a license token, it will try to validate the license token offline, calling /licenses/validate-token.

  2. If you only provided a license token, it will first attempt to validate it to extract the license ID, and then call /licenses/validate-token.

The license is considered valid, if one of the following conditions is met:

  1. There is a network connection available and the license key could be validated online.
  2. There is no network connection available and the license token could be validated offline.

The license is considered invalid, if one of the following conditions is met:

  1. There is no network connection available and no license token was provided, or the token validation failed.
  2. The (online) license key validation failed.

Returns

  • isValid
    isValid
    Type
    boolean
    Description

    Whether the license is valid.

  • validationMethod
    validationMethod
    Type
    string
    Description

    The validation method used to validate the license. Either key or token.

Method call

import UnlocktopusClient from 'unlocktopus-client'
const unlocktopus = new UnlocktopusClient({ ... })

try {
  const { isValid } = await unlocktopus.validate()

  if (isValid) {
  // handle the case where the license key is valid
  }
  else {
    // handle the case where an invalid license key is provided
  }
} catch (error) {
  // handle errors: e.g. license not found
}

Example response

{
  "isValid": true,
  "validationMethod": "key",
}
.validateLicenseKey()

Validate the license key

This method internally calls /licenses/validate-key to validate the license key.

Returns

See /licenses/validate-key for more information.

Method call

try {
  const { isValid } = await unlocktopus.validateLicenseKey()

  if (isValid) {
    // handle the case where the license key is valid
  }
  else {
    // handle the case where an invalid license key is provided
  }
} catch (error) {
  // handle errors: e.g. license not found
}

Example response

{
  "isValid": true,
  "reason": null,
  "timestamp": "2024-09-09T00:00:00Z",
  "license": {
    "id": "49cdf099-94ca-4da9-b07a-71d21a7c918a",
    "object": "License",
    "key": "ABCD-1234-EFGH-5678",
    "maxActivations": 15,
    "status": "active",
    "expirationDate": "2025-12-31T23:59:59Z",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z",
    "productId": "40833d2f-3dc8-4d8a-a5c5-7715043362fc",
    "statusDetails": {
      "isRevoked": false,
      "isExpired": false,
      "determinedAt": "2024-09-26T11:28:34Z"
    }
  }
}
.validateTokenOffline()

Validate the license token offline

This method validates the license token, using your product's public key. It returns the encoded information (expiration date, product ID, and everything you've passed as payload when you created the token).

Returns

  • licenseId
    licenseId
    Type
    string
    Description

    The unique identifier of the License.

  • expiresAt
    expiresAt
    Type
    string
    Description

    The expiration date of the License.

  • productId
    productId
    Type
    string
    Description

    The unique identifier of the Product that the License belongs to.

  • customPayload
    customPayload
    Type
    object | null
    Description

    The custom payload you included when creating the token

Method call

import UnlocktopusClient from 'unlocktopus-client'
const unlocktopus = new UnlocktopusClient({ ... })

try {
  const tokenPayload = await unlocktopus.validateTokenOffline()
  // continue with your logic handling a successful validation
} catch (error) {
  if (error instanceof UnlocktopusError) {
    // handle the case where the token is invalid
    // error documentation is coming soon
  } else {
    // handle other errors
  }
}

Example token payload

{
  "licenseId": "[LICENSE_ID]",
  "productId": "[PRODUCT_ID]",
  "expiresAt": "2025-12-31T23:59:59Z",
  "customPayload": {
    "featureFlags": ["feature1", "feature2"]
  }
}