Check License

Endpoint

• Method: GET
• Path: /api/v4/check_license
• Description: Checks the status and validity of a license.

Authentication

See License API Authorization.

Required headers

• Date (string) — RFC7231 GMT date string
• Authorization (string) — signature or bearer token

Optional headers

• licensespring-tpm-signature (string) — TPM licensing signature and algorithm

  • licensespring-tpm-signature: algorithm="ES256",signature=""

Recommended headers

• Accept: application/json

Request

Query parameters

Required:

• hardware_id (string) — Unique hardware ID generated for the client device
• product (string) — Product short code

One of:

• license_key (string) — Required if product is key-based
• username (string) — Required if product is user-based

Optional:

• license_id (number) — Targets a specific license ID
• include_expired_features (boolean)
• env (string)
• os_ver (string)
• hostname (string)
• os_hostname (string)
• ip (string)
• ip_local (string)
• app_ver (string)
• sdk_ver (string)
• mac_address (string)
• include_scheduled_changes (boolean)

Examples

curl

curl --location --request GET '/api/v4/check_license?hardware_id=string&product=string&license_key=string' \
--header 'Accept: application/json' \
--header 'Date: string' \
--header 'Authorization: string'

nodejs

var request = require('request');
var options = {
  method: 'GET',
  url: '/api/v4/check_license?hardware_id=string&product=string&license_key=string',
  headers: {
    'Accept': 'application/json',
    'Date': 'string',
    'Authorization': 'string'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

javascript (fetch)

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Date", "string");
myHeaders.append("Authorization", "string");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("/api/v4/check_license?hardware_id=string&product=string&license_key=string", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

python

import requests

url = "/api/v4/check_license?hardware_id=string&product=string&license_key=string"

headers = {
  "Accept": "application/json",
  "Date": "string",
  "Authorization": "string"
}

response = requests.get(url, headers=headers)
print(response.text)

ruby

require "uri"
require "net/http"

url = URI("/api/v4/check_license?hardware_id=string&product=string&license_key=string")

http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Accept"] = "application/json"
request["Date"] = "string"
request["Authorization"] = "string"

response = http.request(request)
puts response.read_body

Schema

Request schema (TypeScript + JSON Schema)

TypeScript

type LicenseCheckQueryParameters = ({

  // for key-based licenses:
  license_key: string

} | {

  // for user-based licenses:
  username: string

}) & {

  // required properties:
  hardware_id: string
  product: string

  // optional properties:
  license_id?: number | undefined
  is_vm?: boolean | undefined
  vm_info?: string | undefined
  os_ver?: string | undefined
  hostname?: string | undefined
  os_hostname?: string | undefined
  ip?: string | undefined
  ip_local?: string | undefined
  app_ver?: string | undefined
  sdk_ver?: string | undefined
  mac_address?: string | undefined
  include_expired_features?: boolean | undefined
  include_scheduled_changes?: boolean | undefined
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "allOf": [
    {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "license_key": { "type": "string" }
          },
          "required": ["license_key"],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "username": { "type": "string" }
          },
          "required": ["username"],
          "additionalProperties": false
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "hardware_id": { "type": "string" },
        "product": { "type": "string" },
        "license_id": { "type": "number" },
        "is_vm": { "type": "boolean" },
        "vm_info": { "type": "string" },
        "os_ver": { "type": "string" },
        "hostname": { "type": "string" },
        "os_hostname": { "type": "string" },
        "ip": { "type": "string" },
        "ip_local": { "type": "string" },
        "app_ver": { "type": "string" },
        "sdk_ver": { "type": "string" },
        "mac_address": { "type": "string" },
        "include_expired_features": { "type": "boolean" },
        "include_scheduled_changes": { "type": "boolean" },
      },
      "required": ["hardware_id", "product"],
      "additionalProperties": false
    }
  ]
}

Response schema (TypeScript + JSON Schema)

TypeScript

type LicenseScheduledChange = {
  scheduled_at: string,
  status: string,
  action: 'update' | 'reset',
  update_data: JSON,
};

type ProductFeatureScheduledChange = {
  scheduled_at: string,
  status: string,
  product_feature_id: number,
  update_data: JSON,
};

type CustomFieldScheduledChange = {
  scheduled_at: string,
  status: string,
  product_custom_field_id: number,
  update_data: JSON,
};

type ScheduledChanges = {
  license: LicenseScheduledChange[],
  product_feature: ProductFeatureScheduledChange[],
  custom_field: CustomFieldScheduledChange[],
};

type LicenseCheckResponseBody = {
  id: number,
  allow_grace_period: boolean,
  allow_overages: boolean,
  allow_unlimited_activations: boolean,
  borrowed_until: string | null,
  can_borrow: boolean,
  channel: string,
  device_id: number,
  enable_maintenance_period: boolean
  environment: string,
  eula_link: string,
  floating_timeout: number,
  grace_period: number,
  hash_md5: string,
  installation_file: string,
  is_air_gapped: boolean,
  is_borrowed: boolean,
  is_expired: boolean,
  is_floating_cloud: boolean,
  is_floating: boolean,
  is_hardware_key_auth: boolean,
  is_tpm_auth: boolean,
  is_local_license: boolean,
  license_active: boolean,
  license_enabled: boolean,
  license_signature: string,
  license_signature_v2: string,
  offline_signature: string,
  license_type: string,
  maintenance_period: string | null,
  max_activations: number,
  max_borrow_time: number,
  max_license_users: number,
  max_overages: number,
  max_transfers: number,
  order_store_id: string,
  prevent_vm: boolean,
  release_date: string,
  release_notes_link: string,
  requires_version: string,
  size: string,
  start_date: string | null,
  times_activated: number,
  transfer_count: number,
  validity_period: string | null,
  version: string,
  company: { id: number },
  
  product_features: ({
    id: number,
    code: string,
    name: string,
    expiry_date: string,
    metadata: JSON,
    feature_type: 'activation' | 'consumption',
    is_floating: boolean,
    is_floating_cloud: boolean,

    floating_users: number,
    floating_timeout: number,

    max_consumption: number,
    allow_unlimited_consumptions: boolean,
    total_consumptions: number,
    allow_overages: number,
    max_overages: number,
    reset_consumption: boolean,
    consumption_period: 'daily' | 'weekly' | 'monthly' | 'annualy' | null
  })[],
  
  custom_fields: ({
    name: string,
    data_type: 'numer' | 'text' | 'date/time',
    value: string,
  })[],
  
  customer: {
    email: string,
    company_name: string,
    reference: string,
    phone: string,
    first_name: string,
    last_name: string,
    city: string,
    postcode: string,
    state: string,
    country: string,
    address: string,
    customer_account: string | null,
    metadata: JSON,
  },
  
  product_details: {
    product_id: number,
    product_name: string,
    short_code: string,
    authorization_method: 'license-key' | 'user',
    metadata: JSON,
  },
  
  metadata: JSON,
  
  scheduled_changes?: ScheduledChanges,
  trial_days?: number,
  floating_in_use_devices?: number,
  floating_users?: number,
  max_consumptions?: number,
  total_consumptions?: number,
  allow_unlimited_consumptions?: boolean,
  reset_consumption?: boolean,
  consumption_period?: string | null

} & ({

  // for key-based licenses:
  license_key: string,

} | {

  // for user-based licenses:
  user: {
    id: number,
    email: string,
    first_name: string,
    last_name: string,
    phone_number: string,
    is_initial_password: boolean,
    max_activations: number,
    allow_unlimited_activations: boolean,
    total_activations: number
  }
});

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "unevaluatedProperties": false,
  "allOf": [
    {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "license_key": { "type": "string" }
          },
          "required": ["license_key"]
        },
        {
          "type": "object",
          "properties": {
            "user": {
              "type": "object",
              "properties": {
                "id": { "type": "number" },
                "email": { "type": "string" },
                "first_name": { "type": "string" },
                "last_name": { "type": "string" },
                "phone_number": { "type": "string" },
                "is_initial_password": { "type": "boolean" },
                "max_activations": { "type": "number" },
                "allow_unlimited_activations": { "type": "boolean" },
                "total_activations": { "type": "number" }
              },
              "required": ["id", "email", "first_name", "last_name", "phone_number", "is_initial_password", "max_activations", "allow_unlimited_activations", "total_activations"],
              "additionalProperties": false
            }
          },
          "required": ["user"]
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "id": { "type": "number" },
        "allow_grace_period": { "type": "boolean" },
        "allow_overages": { "type": "boolean" },
        "allow_unlimited_activations": { "type": "boolean" },
        "borrowed_until": { "type": ["string", "null"] },
        "can_borrow": { "type": "boolean" },
        "channel": { "type": "string" },
        "device_id": { "type": "number" },
        "enable_maintenance_period": { "type": "boolean" },
        "environment": { "type": "string" },
        "eula_link": { "type": "string" },
        "floating_timeout": { "type": "number" },
        "grace_period": { "type": "number" },
        "hash_md5": { "type": "string" },
        "installation_file": { "type": "string" },
        "is_air_gapped": { "type": "boolean" },
        "is_borrowed": { "type": "boolean" },
        "is_expired": { "type": "boolean" },
        "is_floating_cloud": { "type": "boolean" },
        "is_floating": { "type": "boolean" },
        "is_hardware_key_auth": { "type": "boolean" },
        "is_tpm_auth": { "type": "boolean" },
        "is_local_license": { "type": "boolean" },
        "license_active": { "type": "boolean" },
        "license_enabled": { "type": "boolean" },
        "license_signature": { "type": "string" },
        "license_signature_v2": { "type": "string" },
        "offline_signature": { "type": "string" },
        "license_type": { "type": "string" },
        "maintenance_period": { "type": ["string", "null"] },
        "max_activations": { "type": "number" },
        "max_borrow_time": { "type": "number" },
        "max_license_users": { "type": "number" },
        "max_overages": { "type": "number" },
        "max_transfers": { "type": "number" },
        "order_store_id": { "type": "string" },
        "prevent_vm": { "type": "boolean" },
        "release_date": { "type": "string" },
        "release_notes_link": { "type": "string" },
        "requires_version": { "type": "string" },
        "size": { "type": "string" },
        "start_date": { "type": ["string", "null"] },
        "times_activated": { "type": "number" },
        "transfer_count": { "type": "number" },
        "validity_period": { "type": ["string", "null"] },
        "version": { "type": "string" },
        "company": { "type": "object", "properties": { "id": { "type": "number" } } },
        "product_features": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "number" },
              "code": { "type": "string" },
              "name": { "type": "string" },
              "expiry_date": { "type": "string" },
              "metadata": {},
              "feature_type": { "type": "string", "enum": ["activation", "consumption"] },
              "is_floating": { "type": "boolean" },
              "is_floating_cloud": { "type": "boolean" },
              "floating_users": { "type": "number" },
              "floating_timeout": { "type": "number" },
              "max_consumption": { "type": "number" },
              "allow_unlimited_consumptions": { "type": "boolean" },
              "total_consumptions": { "type": "number" },
              "allow_overages": { "type": "number" },
              "max_overages": { "type": "number" },
              "reset_consumption": { "type": "boolean" },
              "consumption_period": {
                "type": ["string", "null"],
                "enum": ["daily", "weekly", "monthly", "annualy", null]
              }
            },
            "required": ["id", "code", "name", "expiry_date", "metadata", "feature_type", "is_floating", "is_floating_cloud"]
          }
        },
        "custom_fields": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "data_type": { "type": "string", "enum": ["numer", "text", "date/time"] },
              "value": { "type": "string" }
            },
            "required": ["name", "data_type", "value"]
          }
        },
        "customer": {
          "type": "object",
          "properties": {
            "email": { "type": "string" },
            "company_name": { "type": "string" },
            "reference": { "type": "string" },
            "phone": { "type": "string" },
            "first_name": { "type": "string" },
            "last_name": { "type": "string" },
            "city": { "type": "string" },
            "postcode": { "type": "string" },
            "state": { "type": "string" },
            "country": { "type": "string" },
            "address": { "type": "string" },
            "customer_account": { "type": ["string", "null"] },
            "metadata": {}
          },
          "required": ["email", "company_name", "reference", "phone", "first_name", "last_name", "city", "postcode", "state", "country", "address", "metadata"]
        },
        "product_details": {
          "type": "object",
          "properties": {
            "product_id": { "type": "number" },
            "product_name": { "type": "string" },
            "short_code": { "type": "string" },
            "authorization_method": { "type": "string", "enum": ["license-key", "user"] },
            "metadata": {}
          },
          "required": ["product_id", "product_name", "short_code", "authorization_method", "metadata"]
        },
        "metadata": {},
        "scheduled_changes": {
          "type": "object",
          "properties": {
            "license": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "scheduled_at": { "type": "string" },
                  "status": { "type": "string" },
                  "action": { "type": "string", "enum": ["update", "reset"] },
                  "update_data": {}
                },
                "required": ["scheduled_at", "status", "action", "update_data"]
              }
            },
            "product_feature": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "scheduled_at": { "type": "string" },
                  "status": { "type": "string" },
                  "product_feature_id": { "type": "number" },
                  "update_data": {}
                },
                "required": ["scheduled_at", "status", "product_feature_id", "update_data"]
              }
            },
            "custom_field": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "scheduled_at": { "type": "string" },
                  "status": { "type": "string" },
                  "product_custom_field_id": { "type": "number" },
                  "update_data": {}
                },
                "required": ["scheduled_at", "status", "product_custom_field_id", "update_data"]
              }
            }
          },
          "required": ["license", "product_feature", "custom_field"]
        },
        "trial_days": { "type": "number" },
        "floating_in_use_devices": { "type": "number" },
        "floating_users": { "type": "number" },
        "max_consumptions": { "type": "number" },
        "total_consumptions": { "type": "number" },
        "allow_unlimited_consumptions": { "type": "boolean" },
        "reset_consumption": { "type": "boolean" },
        "consumption_period": { "type": ["string", "null"] }
      },
      "required": [
        "id",
        "allow_grace_period",
        "allow_overages",
        "allow_unlimited_activations",
        "can_borrow",
        "channel",
        "device_id",
        "enable_maintenance_period",
        "environment",
        "eula_link",
        "floating_timeout",
        "grace_period",
        "hash_md5",
        "installation_file",
        "is_air_gapped",
        "is_borrowed",
        "is_expired",
        "is_floating_cloud",
        "is_floating",
        "is_hardware_key_auth",
        "is_tpm_auth",
        "license_active",
        "license_enabled",
        "license_signature",
        "license_type",
        "max_activations",
        "max_borrow_time",
        "max_license_users",
        "max_overages",
        "max_transfers",
        "order_store_id",
        "prevent_vm",
        "release_date",
        "release_notes_link",
        "requires_version",
        "size",
        "times_activated",
        "transfer_count",
        "version",
        "product_features",
        "custom_fields",
        "customer",
        "product_details",
        "metadata"
      ]
    }
  ]
}

Response Signatures

The response object contains the following digital signatures:

• license_signature: see the Response Signature article
• license_signature_v2: see the Response Signature v2 article
• offline_signature: can be used for activating/deactivating using the offline method, see Deactivate License (Offline Method)

License Authorization Method

There are two authorization methods for products:

Key-based product licenses

• Client provides license_key in requests for key-based products.
• Response includes license_key and product_details.authorization_method = "license_key".

User-based product licenses

• Client provides username in requests for user-based products.
• Response includes product_details.authorization_method = "user" and a user object with license user details.

License Types

The license_type property defines one of these types:

• perpetual
• time-limited
• subscription
• consumption

For more information see: License Types

Errors

If an error occurs, HTTP status will be 400 or higher and the body will use this format:

Error schema (TypeScript + JSON Schema)

{
  status: number,
  code: string,
  message: string
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "number" },
    "code": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": [
    "status",
    "code",
    "message"
  ],
  "additionalProperties": false
}

List of exceptions

• missing_headers (400): Some headers are missing
• unknown_product (400): Provided product was not found
• license_not_found (400): License with the provided license user not found
• license_not_enabled (400): The license is not enabled
• license_not_active (400): The license is not active
• device_not_found (400): An active device matching the hardware_id not found
• blacklisted (400): This device is blacklisted
• license_not_enough_consumptions (400): Not enough consumptions left
• floating_not_available (400): No available slots for floating license
• product_version_not_supported (400): License product version does not support the app_ver sent in the request
• tpm_invalid_public_key (400): The TPM public key sent is not valid
• tpm_signature_required (400): The TPM signature is missing from the header and TPM usage is enforced
• tpm_signature_missmatch (400): The TPM signature/algorithm is not ES256 and the signature can't be verified against the TPM public key