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

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)

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

javascript (fetch)

python

ruby

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
}

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" }
      },
      "required": ["hardware_id", "product"],
      "additionalProperties": false
    }
  ]
}

Response schema (TypeScript)

TypeScript

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,
  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,
  
  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
  }
});

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