Trial Key

Endpoint

• Method: GET

• Path: /api/v4/trial_key

• Description: Creates and returns a trial license.

Authentication

See License API Authorization.

Required headers

• Date (string)

• Authorization (string)

Recommended headers

• Accept: application/json

Request

Query parameters

Required:

• hardware_id (string)

• product (string)

Optional (user-based products):

• email (string)

• password (string)

• first_name (string)

• last_name (string)

• phone (string)

Optional:

• license_policy (string)

• customer metadata fields (address, postcode, state, country, city, reference)

Interactive reference (raw)

:::note

{
  "tab": "examples",
  "url": "/api/v4/trial_key",
  "name": "/api/v4/trial_key ",
  "method": "GET",
  "request": {
    "pathParameters": [],
    "queryParameters": [
      {
        "kind": "required",
        "name": "hardware_id",
        "type": "string",
        "children": [],
        "description": "In RFC7231 format (see \"License API Authorization\"), eg.: Thu, 17 Nov 2022 20:51:35 GMT"
      },
      {
        "kind": "required",
        "name": "product",
        "type": "string",
        "children": [],
        "description": "Product short code"
      },
      {
        "kind": "optional",
        "name": "email",
        "type": "string",
        "children": [],
        "description": "Required if product is user based. Attach the assigned license user email (eq. [email protected])"
      },
      {
        "name": "license_policy",
        "kind": "optional",
        "type": "string",
        "description": "Sets license policy (license policy code), if omited the default license policy for the product will be used",
        "children": []
      },
      {
        "name": "first_name",
        "kind": "optional",
        "type": "string",
        "description": "Optional. For user-based product licenses only",
        "children": []
      },
      {
        "name": "last_name",
        "kind": "optional",
        "type": "string",
        "description": "Optional. For user-based product licenses only",
        "children": []
      },
      {
        "name": "phone",
        "kind": "optional",
        "type": "string",
        "description": "Optional. For user-based product licenses only",
        "children": []
      },
      {
        "name": "password",
        "kind": "optional",
        "type": "string",
        "description": "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",
        "children": []
      }
    ],
    "headerParameters": [
      {
        "kind": "required",
        "name": "Date",
        "type": "string",
        "children": [],
        "description": "In RFC7231 format (see \"License API Authorization\"), eg.: Thu, 17 Nov 2022 20:51:35 GMT"
      },
      {
        "kind": "required",
        "name": "Authorization",
        "type": "string",
        "children": [],
        "description": "See \"License API Authorization\" article"
      }
    ],
    "bodyDataParameters": [],
    "formDataParameters": []
  },
  "results": {
    "languages": [
      {
        "id": "QLX3IFr3FPKeqNnhkuAXk",
        "code": "{\n    \"license_key\": \"T7GB-C4JX-4Y8R-1234\",\n    \"id\": 1737130277841509,\n    \"order_id\": 1737130277837489,\n    \"product_id\": 1,\n    \"created_at\": 1737130277925,\n    \"updated_at\": 1737130277925,\n    \"max_activations\": 1,\n    \"times_activated\": 0,\n    \"is_trial\": true,\n    \"active\": false,\n    \"enabled\": true,\n    \"trial_days\": 15,\n    \"license_type\": \"time-limited\",\n    \"max_transfers\": 0,\n    \"prevent_vm\": false,\n    \"enable_maintenance_period\": false,\n    \"maintenance_duration\": null,\n    \"metadata\": {},\n    \"is_hardware_key_auth\": false,\n    \"validity_period\": null,\n    \"LicenseProductFeatures\": [\n        {\n            \"id\": \"1737130277926519\",\n            \"product_feature_id\": 5,\n            \"max_consumption\": 10,\n            \"allow_overages\": false,\n            \"max_overages\": 0,\n            \"reset_consumption\": false,\n            \"consumption_period\": null,\n            \"expiry_date\": null,\n            \"metadata\": {},\n            \"is_floating\": false,\n            \"is_floating_cloud\": false\n        }\n    ],\n    \"LicenseCustomFields\": [],\n    \"license\": \"T7GB-C4JX-4Y8R-1234\"\n}",
        "language": "200",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "QLX3IFr3FPKeqNnhkuAXk"
  },
  "examples": {
    "languages": [
      {
        "id": "GCdqGE3Uarg-ovc11AFKF",
        "language": "curl",
        "code": "curl --location --request GET '/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string' \\\n--header 'Accept: application/json' \\\n--header 'Date: string' \\\n--header 'Authorization: string'",
        "customLabel": ""
      },
      {
        "id": "kVmRuRWFg1WdVHBr_jJsI",
        "language": "nodejs",
        "code": "var request = require('request');\nvar options = {\n   'method': 'GET',\n   'url': '/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string',\n   'headers': {\n      'Accept': 'application/json',\n      'Date': 'string',\n      'Authorization': 'string'\n   }\n};\nrequest(options, function (error, response) {\n   if (error) throw new Error(error);\n   console.log(response.body);\n});\n",
        "customLabel": ""
      },
      {
        "id": "VzSNg-xq9B50TtFX7fGlE",
        "language": "javascript",
        "code": "var myHeaders = new Headers();\nmyHeaders.append(\"Accept\", \"application/json\");\nmyHeaders.append(\"Date\", \"string\");\nmyHeaders.append(\"Authorization\", \"string\");\n\nvar requestOptions = {\n   method: 'GET',\n   headers: myHeaders,\n   redirect: 'follow'\n};\n\nfetch(\"/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));",
        "customLabel": ""
      },
      {
        "id": "FANx6WPBmq3niAudJgpuM",
        "language": "python",
        "code": "import requests\n\nurl = \"/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string\"\n\npayload={}\nheaders = {\n   'Accept': 'application/json',\n   'Date': 'string',\n   'Authorization': 'string'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n",
        "customLabel": ""
      },
      {
        "id": "Z5q0sg9XmQTNVHKXuCjN_",
        "language": "ruby",
        "code": "require \"uri\"\nrequire \"net/http\"\n\nurl = URI(\"/api/v4/trial_key?hardware_id=string&product=string&license_key=string&username=string\")\n\nhttp = Net::HTTP.new(url.host, url.port);\nrequest = Net::HTTP::Get.new(url)\nrequest[\"Accept\"] = \"application/json\"\nrequest[\"Date\"] = \"string\"\nrequest[\"Authorization\"] = \"string\"\n\nresponse = http.request(request)\nputs response.read_body\n",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "FANx6WPBmq3niAudJgpuM"
  },
  "description": "Creates and returns a trial license",
  "currentNewParameter": {
    "label": "Query Parameter",
    "value": "queryParameters"
  }
}

:::

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

type TrialKeyRequestParameters = {
  
  // required parameters:
  product: string,
  hardware_id: string,
  
  // required for user-based products:
  email?: string | undefined,
  
  // 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,
  address?: string | undefined,
  postcode?: string | undefined,
  state?: string | undefined,
  country?: string | undefined,
  city?: string | undefined,
  reference?: string | undefined,
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": { "type": "string" },
    "hardware_id": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "password": { "type": ["string"] },
    "license_policy": { "type": ["string"] },
    "first_name": { "type": ["string"] },
    "last_name": { "type": ["string"] },
    "phone": { "type": ["string"] },
    "address": { "type": ["string"] },
    "postcode": { "type": ["string"] },
    "state": { "type": ["string"] },
    "country": { "type": ["string"] },
    "city": { "type": ["string"] },
    "reference": { "type": ["string"] }
  },
  "oneOf": [
    { "required": ["product", "hardware_id"] },
    { "required": ["product", "hardware_id", "email"] }
  ],
  "additionalProperties": false
}

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

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

{
    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,
}

Examples

curl

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

nodejs

javascript (fetch)

python

ruby

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

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