License API
Trial Key

9min
Creates and returns a trial license
GET
Request
Query Parameters
hardware_id
required
String
In RFC7231 format (see "License API Authorization"), eg.: Thu, 17 Nov 2022 20:51:35 GMT
product
required
String
Product short code
email
optional
String
Required if product is user based. Attach the assigned license user email (eq. [email protected])
license_policy
optional
String
Sets license policy (license policy code), if omited the default license policy for the product will be used
first_name
optional
String
Optional. For user-based product licenses only
last_name
optional
String
Optional. For user-based product licenses only
phone
optional
String
Optional. For user-based product licenses only
password
optional
String
Only for user-based licenses: Sets the license user's password. If not provided, a random password will be generated and returned in the response
Header Parameters
Date
required
String
In RFC7231 format (see "License API Authorization"), eg.: Thu, 17 Nov 2022 20:51:35 GMT
Authorization
required
String
See "License API Authorization" article
Curl
Node.js
JS
Python
Ruby
import requests

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

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

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

import requests

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

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

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
Responses
200
{
    "license_key": "T7GB-C4JX-4Y8R-1234",
    "id": 1737130277841509,
    "order_id": 1737130277837489,
    "product_id": 1,
    "created_at": 1737130277925,
    "updated_at": 1737130277925,
    "max_activations": 1,
    "times_activated": 0,
    "is_trial": true,
    "active": false,
    "enabled": true,
    "trial_days": 15,
    "license_type": "time-limited",
    "max_transfers": 0,
    "prevent_vm": false,
    "enable_maintenance_period": false,
    "maintenance_duration": null,
    "metadata": {},
    "is_hardware_key_auth": false,
    "validity_period": null,
    "LicenseProductFeatures": [
        {
            "id": "1737130277926519",
            "product_feature_id": 5,
            "max_consumption": 10,
            "allow_overages": false,
            "max_overages": 0,
            "reset_consumption": false,
            "consumption_period": null,
            "expiry_date": null,
            "metadata": {},
            "is_floating": false,
            "is_floating_cloud": false
        }
    ],
    "LicenseCustomFields": [],
    "license": "T7GB-C4JX-4Y8R-1234"
}
{
    "license_key": "T7GB-C4JX-4Y8R-1234",
    "id": 1737130277841509,
    "order_id": 1737130277837489,
    "product_id": 1,
    "created_at": 1737130277925,
    "updated_at": 1737130277925,
    "max_activations": 1,
    "times_activated": 0,
    "is_trial": true,
    "active": false,
    "enabled": true,
    "trial_days": 15,
    "license_type": "time-limited",
    "max_transfers": 0,
    "prevent_vm": false,
    "enable_maintenance_period": false,
    "maintenance_duration": null,
    "metadata": {},
    "is_hardware_key_auth": false,
    "validity_period": null,
    "LicenseProductFeatures": [
        {
            "id": "1737130277926519",
            "product_feature_id": 5,
            "max_consumption": 10,
            "allow_overages": false,
            "max_overages": 0,
            "reset_consumption": false,
            "consumption_period": null,
            "expiry_date": null,
            "metadata": {},
            "is_floating": false,
            "is_floating_cloud": false
        }
    ],
    "LicenseCustomFields": [],
    "license": "T7GB-C4JX-4Y8R-1234"
}
﻿
For a trial license to be created, the product must have trial licenses enabled by setting allow_trial to true.
By default, the same combination of hardwareID and product will generate the same trial key. This ensures that users cannot obtain multiple trial keys on the same device.
If you want to permit multiple trial licenses on the same device, you can enable this feature by adjusting the Allow multiple licenses on trial setting in the vendor platform under your company account settings.
Schema
Request Query Parameters
TypeScript
JSON
type TrialKeyRequestParameters = {
  
  // required parameters:
  product: string,
  hardware_id: string,
  
  // required for key-based products:
  license_key: string,
  
  // required for user-based products:
  email: string,
  
  // optional for user-based products:
  password?: string | undefined,
  
  // optional property:
  license_policy?: string | undefined,
  
  // if any of the following optional properties is set, a Customer is created for (or associated to) this Trial Key request:
  first_name?: string | undefined,
  last_name?: string | undefined,
  phone?: string | undefined,
  phone?: string | undefined,
  address?: string | undefined,
  postcode?: string | undefined,
  state?: string | undefined,
  country?: string | undefined,
  city?: string | undefined,
  reference:?: string | undefined,
}
type TrialKeyRequestParameters = {
  
  // required parameters:
  product: string,
  hardware_id: string,
  
  // required for key-based products:
  license_key: string,
  
  // required for user-based products:
  email: string,
  
  // optional for user-based products:
  password?: string | undefined,
  
  // optional property:
  license_policy?: string | undefined,
  
  // if any of the following optional properties is set, a Customer is created for (or associated to) this Trial Key request:
  first_name?: string | undefined,
  last_name?: string | undefined,
  phone?: string | undefined,
  phone?: string | undefined,
  address?: string | undefined,
  postcode?: string | undefined,
  state?: string | undefined,
  country?: string | undefined,
  city?: string | undefined,
  reference:?: string | undefined,
}
﻿
Response Body
The response from this endpoint will differ depending in whether a trial license already exists for the requested product, hardware ID and email* (*if using user-based license)
1. If a new trial license is being created
TypeScript
JSON
type TrialKeyResponseBody = {

  id: number,
  license_type: 'perpetual' | 'time-limited' | 'consumption' | 'subscription',
  order_id: number,
  product_id: number,
  max_activations: number,
  times_activated: number,
  is_trial: true,
  active: boolean,
  enabled: boolean,
  max_transfers: number,
  trial_days: number,
  maintenance_duration: string | null, // Length of time expressed in days, months or years, e.g. 5d, 2m, 3y
  validity_period: string | null, // Date string in full ISO 8601 format, e.g. "2024-09-27T23:30:48.016Z"
  enable_maintenance_period: boolean,
  prevent_vm: boolean,
  is_hardware_key_auth: boolean,
  initial_password: string,
  metadata: JSON,
  created_at: number, // UNIX Timestamp in milliseconds
  updated_at: number, // UNIX Timestamp in milliseconds
  
  LicenseProductFeatures: ({
    id: number,
    product_feature_id: number,
    max_consumption: number,
    allow_overages: boolean,
    max_overages: number,
    reset_consumption: number,
    consumption_period: string | null,
    expiry_date: string | null, // Date string in full ISO 8601 format, e.g. "2024-09-27T23:30:48.016Z"
    is_floating: boolean,
    is_floating_cloud: boolean,
    metadata: JSON,
    
    // the following properties are only present if is_floating=true or is_floating_cloud=true
    floating_timeout: number,
    floating_users: number,
  })[],
  
  LicenseCustomFields: {
    product_custom_field_id: number,
    value: string
  }[],
  
  // the following properties are only present for key-based product licenses
  license: string,
  license_key: string,
  
  // the following properties are only present for user-based product licenses
  license_user: string,
  initial_password: string,
  max_license_users: number,
  license_user_id: number | null,
  
  // the following properties are only present if license_type="subscription"
  grace_period: number,
  allow_grace_period: boolean,
  
  // the following properties are only present if license_type="consumption"
  allow_overages: boolean,
  max_overages: number,
  max_consumptions: number,
  valid_duration: null,
  consumption_period: string | null,
  reset_consumption: boolean,
}
type TrialKeyResponseBody = {

  id: number,
  license_type: 'perpetual' | 'time-limited' | 'consumption' | 'subscription',
  order_id: number,
  product_id: number,
  max_activations: number,
  times_activated: number,
  is_trial: true,
  active: boolean,
  enabled: boolean,
  max_transfers: number,
  trial_days: number,
  maintenance_duration: string | null, // Length of time expressed in days, months or years, e.g. 5d, 2m, 3y
  validity_period: string | null, // Date string in full ISO 8601 format, e.g. "2024-09-27T23:30:48.016Z"
  enable_maintenance_period: boolean,
  prevent_vm: boolean,
  is_hardware_key_auth: boolean,
  initial_password: string,
  metadata: JSON,
  created_at: number, // UNIX Timestamp in milliseconds
  updated_at: number, // UNIX Timestamp in milliseconds
  
  LicenseProductFeatures: ({
    id: number,
    product_feature_id: number,
    max_consumption: number,
    allow_overages: boolean,
    max_overages: number,
    reset_consumption: number,
    consumption_period: string | null,
    expiry_date: string | null, // Date string in full ISO 8601 format, e.g. "2024-09-27T23:30:48.016Z"
    is_floating: boolean,
    is_floating_cloud: boolean,
    metadata: JSON,
    
    // the following properties are only present if is_floating=true or is_floating_cloud=true
    floating_timeout: number,
    floating_users: number,
  })[],
  
  LicenseCustomFields: {
    product_custom_field_id: number,
    value: string
  }[],
  
  // the following properties are only present for key-based product licenses
  license: string,
  license_key: string,
  
  // the following properties are only present for user-based product licenses
  license_user: string,
  initial_password: string,
  max_license_users: number,
  license_user_id: number | null,
  
  // the following properties are only present if license_type="subscription"
  grace_period: number,
  allow_grace_period: boolean,
  
  // the following properties are only present if license_type="consumption"
  allow_overages: boolean,
  max_overages: number,
  max_consumptions: number,
  valid_duration: null,
  consumption_period: string | null,
  reset_consumption: boolean,
}
﻿
2. If a trial license already exists
TypeScript
{
    license_type: 'perpetual' | 'time-limited' | 'consumption' | 'subscription',
    is_trial: true,
    
    // the following property is only present on key-based product licenses
    license: string,
    
    // the following property is only present on user-based product licenses
    license_user: string,
}
{
    license_type: 'perpetual' | 'time-limited' | 'consumption' | 'subscription',
    is_trial: true,
    
    // the following property is only present on key-based product licenses
    license: string,
    
    // the following property is only present on user-based product licenses
    license_user: string,
}
﻿
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:
TypeScript
{
  status: number,
  code: string,
  message: string
}
{
  status: number,
  code: string,
  message: string
}
﻿
List of exceptions
missing_parameters (400): Some parameters are missing in the request: { params }
missing_hardware_id (400): The hardware_id missing in the request
unknown_product (400): Provided product was not found
trial_not_allowed (400):Product does not allow trial
email_missing (400): An email is missing for user-based product
﻿
Updated 17 Jan 2025
Did this page help you?
Licenses for Device
Products