Licenses for Device

This endpoint lets you list all licenses assigned to the specified device.

Endpoint

• Method: GET
• Path: /api/v4/device_licenses
• Description: Returns a list of licenses assigned to a device.

Authentication

See License API Authorization.

Required headers

• Date (string) — RFC7231 GMT date string
• Authorization (string)

Recommended headers

• Accept: application/json

Request

Query parameters

• hardware_id (required, string) — Unique hardware ID generated for the client device

Examples

curl

curl --location --request GET '/api/v4/device_licenses?hardware_id=STRING' \
--header 'Accept: application/json' \
--header 'Date: DATE_STRING' \
--header 'Authorization: AUTHORIZATION_STRING'

nodejs

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

javascript (fetch)

const headers = new Headers();
headers.append("Accept", "application/json");
headers.append("Date", "DATE_STRING");
headers.append("Authorization", "AUTHORIZATION_STRING");

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

const queryParams = new URLSearchParams({
  hardware_id: 'HARDWARE_ID_STRING'
}).toString();

fetch("/api/v4/device_licenses?" + queryParams, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

python

import requests

url = "/api/v4/device_licenses?hardware_id=STRING"

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

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

ruby

require "uri"
require "net/http"

url = URI("/api/v4/device_licenses?hardware_id=STRING")

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

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

Example Responses

200

[
    {
        "id": 1702983098133459,
        "order_store_id": "trial_1702983098133439",
        "license_active": true,
        "license_enabled": true,
        "license_type": "subscription",
        "license_key": "H62K-C35N-BS2J-VZ13",
        "is_trial": true,
        "max_license_users": 1,
        "validity_period": "2023-12-20",
        "enable_maintenance_period": false,
        "maintenance_period": null,
        "allow_grace_period": false,
        "grace_period": 0,
        "max_activations": 1,
        "allow_unlimited_activations": true,
        "times_activated": 1,
        "start_date": null,
        "transfer_count": 1,
        "max_transfers": 0,
        "allow_overages": false,
        "max_overages": 0,
        "is_floating_cloud": true,
        "is_floating": false,
        "floating_timeout": 120,
        "floating_in_use_devices": 0,
        "can_borrow": false,
        "max_borrow_time": 0,
        "prevent_vm": false,
        "custom_fields": [],
        "product_features": [
            {
                "id": 1702983421931584,
                "code": "e",
                "name": "e",
                "feature_type": "activation",
                "expiry_date": null,
                "metadata": {},
                "is_floating": false,
                "is_floating_cloud": false
            }
        ],
        "customer": {
            "email": "trial_request",
            "company_name": null,
            "reference": "",
            "phone": "",
            "first_name": null,
            "last_name": null,
            "city": "",
            "postcode": "",
            "state": "",
            "country": "",
            "address": "",
            "customer_account": null,
            "metadata": {}
        },
        "product_details": {
            "product_id": 1584723961091040,
            "product_name": "product1",
            "short_code": "1337",
            "authorization_method": "license-key",
            "metadata": {}
        },
        "metadata": {},
        "is_hardware_key_auth": false,
        "is_air_gapped": false,
        "floating_users": 1,
        "trial_days": 1
    },
    {
        "id": 1700060342999659,
        "order_store_id": "trial_1700060342999639",
        "license_active": false,
        "license_enabled": true,
        "license_type": "subscription",
        "license_key": "H57Y-PS8L-VX6J-WU13",
        "is_trial": true,
        "max_license_users": 1,
        "validity_period": null,
        "enable_maintenance_period": false,
        "maintenance_period": null,
        "allow_grace_period": false,
        "grace_period": 0,
        "max_activations": 1,
        "allow_unlimited_activations": false,
        "times_activated": 0,
        "start_date": null,
        "transfer_count": 0,
        "max_transfers": 0,
        "allow_overages": false,
        "max_overages": 0,
        "is_floating_cloud": true,
        "is_floating": false,
        "floating_timeout": 120,
        "can_borrow": false,
        "max_borrow_time": 0,
        "prevent_vm": false,
        "custom_fields": [],
        "product_features": [
            {
                "id": 1700060342999669,
                "code": "ccc",
                "name": "ccc",
                "feature_type": "activation",
                "expiry_date": null,
                "metadata": {},
                "is_floating": false,
                "is_floating_cloud": true,
                "floating_timeout": 120,
                "floating_users": 1
            }
        ],
        "customer": {
            "email": "trial_request",
            "company_name": null,
            "reference": "",
            "phone": "",
            "first_name": null,
            "last_name": null,
            "city": "",
            "postcode": "",
            "state": "",
            "country": "",
            "address": "",
            "customer_account": null,
            "metadata": {}
        },
        "product_details": {
            "product_id": 1584723961091040,
            "product_name": "product1",
            "short_code": "1337",
            "authorization_method": "license-key",
            "metadata": {}
        },
        "metadata": {},
        "is_hardware_key_auth": false,
        "is_air_gapped": false,
        "floating_users": 1,
        "trial_days": 1
    }
]

\

Schema

Request schema (TypeScript + JSON Schema)

TypeScript

type LicensesForDeviceRequestParameters = {
  hardware_id: string
}

JSON Schema

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

Response schema (TypeScript + JSON Schema)

TypeScript

type ConsumptionPoolState = {
  id: number,
  name: string,
  type: 'license' | 'license_product_feature',
  total_consumptions: number,
  max_consumptions: number,
  allow_overages: boolean,
  max_overages: number,
  allow_unlimited_consumptions: boolean,
  allow_negative_consumptions: boolean
};

type LicensesForDeviceResponseBody = ({
  id: number,
  allow_grace_period: boolean,
  allow_overages: boolean,
  allow_unlimited_activations: boolean,
  borrowed_until: string | null, // in ISO 8601 format (always in UTC timezone), e.g. 2024-09-27T23:30:48.016Z or 2024-09-27 23:30
  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, // string is in DateISO8601UTC format
  version: string,
  company: { id: number },
  pool: ConsumptionPoolState | null,
  
  product_features: ({
    id: number,
    code: string,
    name: string,
    expiry_date: string,
    metadata: JSON,
    feature_type: 'activation' | 'consumption',
    is_floating: boolean,
    is_floating_cloud: boolean,
    pool: ConsumptionPoolState | null,

    // the following properties are only present if is_floating=true or is_floating_cloud=true
    floating_users: number,
    floating_timeout: number,

    // the following properties are only present if feature_type=consumption
    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,
  
  // the following property is only present if is_trial=true
  trial_days: number,
  
  // the following properties is only present if is_floating=true or is_floating_cloud=true
  floating_in_use_devices: number,
  floating_users: number,
  
  // the following properties are only present if license_type='consumption'
  max_consumptions: number,
  total_consumptions: number,
  allow_unlimited_consumptions: boolean,
  reset_consumption: boolean,
  consumption_period: string | null, // string is in DateISO8601UTC format
  
} & ({

  // 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",
  "$defs": {
    "ConsumptionPoolState": {
      "type": "object",
      "properties": {
        "id": { "type": "number" },
        "name": { "type": "string" },
        "type": { "type": "string", "enum": ["license", "license_product_feature"] },
        "total_consumptions": { "type": "number" },
        "max_consumptions": { "type": "number" },
        "allow_overages": { "type": "boolean" },
        "max_overages": { "type": "number" },
        "allow_unlimited_consumptions": { "type": "boolean" },
        "allow_negative_consumptions": { "type": "boolean" }
      },
      "required": ["id", "name", "type", "total_consumptions", "max_consumptions", "allow_overages", "max_overages", "allow_unlimited_consumptions", "allow_negative_consumptions"]
    }
  },
  "type": "array",
  "items": {
    "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" } } },
          "pool": { "anyOf": [{ "$ref": "#/$defs/ConsumptionPoolState" }, { "type": "null" }] },
          "product_features": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "number" },
                "code": { "type": "string" },
                "name": { "type": "string" },
                "expiry_date": { "type": "string" },
                "metadata": { "type": "object" },
                "feature_type": { "type": "string", "enum": ["activation", "consumption"] },
                "is_floating": { "type": "boolean" },
                "is_floating_cloud": { "type": "boolean" },
                "pool": { "anyOf": [{ "$ref": "#/$defs/ConsumptionPoolState" }, { "type": "null" }] },
                "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", "pool"]
            }
          },
          "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": { "type": "object" }
            },
            "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": { "type": "object" }
            },
            "required": ["product_id", "product_name", "short_code", "authorization_method", "metadata"]
          },
          "metadata": { "type": "object" },
          "trial_days": { "type": "number" },
          "floating_users": { "type": "number" },
          "floating_in_use_devices": { "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",
          "license_active",
          "license_enabled",
          "license_signature",
          "license_signature_v2",
          "offline_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",
          "pool",
          "product_features",
          "custom_fields",
          "customer",
          "product_details",
          "metadata"
        ]
      }
    ]
  }
}

Errors

If an error occurs, the response will have an HTTP status code of 400 or higher, and the response body will contain an error description in the following format:

{
  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