The license key structure is used in Partner API 3.0 to hold the information about a license key.

Notes:

  • In the tables below, an omitted field means that the field was absent (omitted) in an incoming HTTP request: It was not present with either null nor with any other value.
  • Fields with the null value (also called null-valued fields) are fields that are present in incoming HTTP requests, but they have a null value.
  • Handling of omitted and null-valued fields by Partner API 3.0 differs from the server side perspective (for details see the tables with field descriptions below). It is necessary to take this into account in order to properly implement integration with Partner API 3.0.

License key structure consists of the following fields:

Field Name Field Type Description Interpretation on Input Interpretation on Output
ownerId JSON string

An ID of a license owner.

You can obtain the ID in Plesk Partner Central: go to the Accounts tab > click the customer’s name > the Internal ID field.

Mandatory if an API account belongs to a reseller.

Optional if an API account belongs to a customer. If omitted when creating a license, the license will be created under an account to which API credentials belong.

The null value is treated as an error.

 Always not null. Holds the ID of a key owner.
keyIdentifiers “Key identifiers” structure (described further in this section) The identifier of a license key.
  • If omitted, no actions.
  • If null, an error occurs.
  • If specified as a non-null value:
    • When the key is created:
      • It is expected that all subfields (“keyId”, “keyNumber”, and “activationCode”) are omitted.
      • Otherwise, an error occurs.
    • When the key is modified:
      • It is expected that at least one subfield (“keyId”, “keyNumber”, or “activationCode”) is specified. The specified subfield will then be checked against the values stored in the key to avoid calling a Partner API 3.0 method for the wrong license key.
      • If no subfields were specified, an error occurs.
 Always not null. Holds the identifiers of a current license key.
parentKeyIdentifiers “Key identifiers” structure (described further in this section) The identifier of a parent license key.
  • If omitted, no actions.
  • If null, then a current license key will be detached from the parent key (if there is any).
  • Otherwise:
    • It is expected that at least one subfield (“keyId”, “keyNumber”, or “activationCode”) is specified. A key matching the values in “keyId”, “keyNumber”, and “activationCode” subfields will be found. The current key will be (re-)attached to the found key.
    • If no subfields specified, an error occurs.
 Null if there is no parent key for this key. Otherwise holds the identifier of a parent key.
childKeyIdentifiers

Array of “Key identifiers” structures

(described further in this section)

 Each array element corresponds to a child license key. This is an informational field. Ignored on input. Always not null. If a license key does not have child keys, this field holds an empty array.
overridingKeyIdentifiers

“Key identifiers” structure

(described further in this section)

 The identifier of the key that overrides the current key. This is an informational field. Ignored on input. Null if there is no key that overrides this key. Otherwise holds the identifier of the overriding key.
activationInfo “Key activation info” structure (described further in this section) Information about activation of a license key.
  • If omitted, no actions.
  • If null:
    • If a key does not support activation, no actions.
    • If a key supports activation, an error occurs.
  • If specified:
    • If a key does not support activation, an error occurs.
    • If a key supports activation:
      • If the uid subfield is omitted, no actions.
      • If the uid subfield is present, then the key with the specified UID is activated (re-activated, deactivated).
 Null if a license key does not support activation. Otherwise non-null “key activation info” structure.
ipAddressBinding JSON string The IP address that a license key is bound to. Can be both IPv4 and IPv6.
  • If omitted, no actions.
  • If null, a license key is unbound from the IP address to which it was bound.
  • Otherwise, (re-)bind a license key to the specified IP address.
 The IP address to which the license key is bound. If no IP address is associated with a license key, the null value is returned.
restrictIPBinding JSON boolean Specifies whether a license key can (false) or cannot (true) be used on IP addresses other than ipAddressBinding.

May be omitted.

If this parameter is omitted on key creation, the value is set according to the account settings - the Default IP Binding.

 Always not null.
productConfigurationId JSON number Product configuration ID.
  • On license key creation:
    • If omitted or null, default product configuration will be associated with the license key (if applicable).
    • If not null:
      • If the specified product configuration is not supported for the license key, an error occurs.
      • Otherwise, the specified product configuration will be associated with the license key.
  • On license key modification:
    • If omitted, no actions.
    • If null:
      • If the specified product configuration is not supported for a license key, no actions.
      • Otherwise, an error occurs.
    • If not null:
      • If the product configuration is not supported for a license key, an error occurs.
      • Otherwise, the specified product configuration will be associated with a license key.

Always not null for license keys that support product configurations.

Null for license keys that do not support product configurations.
nickname JSON string The text information about a license key (such as alias, custom tag, and so on).

If the null value or empty string was specified, the value is reset to an empty string (“”).

Otherwise, the information about a license key is updated with the specified value.

 A non-null value of the description. By default, each license has an empty (“”) description.
items Array of “Key item (key billable component)” structures (described further in this section) The items (billable components) of a license key.

Required for license key creation.

May be omitted in the key modification command. However, if specified, it must have at least one element in the array.

The null value leads to an error.

 A non-empty array of key items (billable components).
creationDate JSON string with timestamp in ISO 8601 format License creation date and time. This is an informational field. Ignored on input. Always not null.
lastModificationDate JSON string with timestamp in ISO 8601 format License last modification date. This is an informational field. Ignored on input. Always not null.
updateDate JSON string with timestamp in ISO 8601 format The date when a license key should be updated the next time. This is an informational field. Ignored on input. Always not null.
expirationDate JSON string with timestamp in ISO 8601 format The date when a license key becomes expired if it was not updated. This is an informational field. Ignored on input. Always not null.
susExpirationDate JSON string with timestamp in ISO 8601 format The date when SUS becomes expired if it would not be renewed. This is an informational field. Ignored on input. Null for licenses without SUS.
susStatus JSON string  with possible values ‘ACTIVE’, ‘EXPIRED’ The SUS status. This is an informational field. Ignored on input. Null for licenses without SUS.
supportExpirationDate JSON string with timestamp in ISO 8601 format The date when support becomes expired. This is an informational field. Ignored on input. Null for licenses without support.
supportStatus JSON string  with possible values ‘ACTIVE’, ‘EXPIRED’ The support status. This is an informational field. Ignored on input. Null for licenses without support.
autoRenew JSON boolean Specifies whether a license key is renewed automatically by Key Administrator.

May be omitted. If present and applicable (a license key is of the Lease or Long Lease type), then the key’s autoRenew flag will be changed to the specified value.

If this parameter is omitted on key creation, the value is set according to the account settings - Default value for Auto-renewal for long-term lease licenses (1 Year and longer), Default value for Auto-renewal for regular lease licenses.
Non-null for lease or long lease,
true for purchased keys,
null otherwise.
terminated JSON boolean Specifies whether a license key is terminated.
May be omitted. If present, then a license key will be terminated depending on the value of this field (true or false respectively).
The null value leads to an error.
 Always not null.
suspended JSON boolean Specifies whether a license key is suspended.

May be omitted. If present, then key will be suspended or resumed depending on the value of this field (true or false respectively).

The null value leads to an error.

 Always not null.
status JSON string with possible values ‘ACTIVE’, ‘EXPIRED’, ‘TERMINATED’, ‘SUSPENDED’. Specifies a license key status. This is an informational field. Ignored on input. Always not null.
ownerSuspended JSON boolean Specifies whether a license key is suspended because its owner is also suspended. This is an informational field. Ignored on input. Always not null.
fraud JSON string Specifies whether a license is detected as being used on multiple Plesk servers. This is an informational field. Ignored on input. Available value: confirmed_multiuse, potential_multiuse. The available value: confirmed_multiuse, potential_multiuse.
lastReportingDate ISO 8601 date and time Date and time when the usage information was received from the key. This is an informational field. Ignored on input. Null if no usage report was received from the key.
lastReportingIp string A set of IP addresses on the host where the key was installed during the last usage report. This is an informational field. Ignored on input. Null if no usage report was received from the key.

The Key Identifiers Structure

The Key identifiers structure encapsulates identifier fields that are unique for a license key and can be used in Key Administrator or Partner Central to address a license key:

Field Name Field Type Description Interpretation on Input Interpretation on Output
keyId JSON number License key number without prefix and version

Ignored if omitted. Otherwise the specified value is checked against the actual number of a key to avoid invocation of Partner API 3.0 method with the wrong key.

The null value leads to an error.

 Always not null. Note that this field can be used for addressing a license key via URL. For example: https://api.central.plesk.com/30/keys/12345678
keyNumber JSON string Full notation of a license key number (with prefix and version)

Ignored if omitted. Otherwise the specified value is checked against the actual number of a key to avoid invocation of a Partner API 3.0 method with the wrong key.

The null value leads to an error.

 Always not null. This field cannot be used for addressing a license key via URL.
activationCode JSON string Activation code (if any)

Ignored if omitted. Otherwise the specified value is checked against the actual activation code of a key to avoid invocation of a Partner API 3.0 method with the wrong key.

The null value is OK if a license key does not have an activation code. Otherwise, the null value leads to an error.

 The null value if a license key does not have activation code. Also, null if a license key belongs to a different owner than the current key. Note that this field can be used for addressing a license key by URL. For example: https://api.central.plesk.com/30/keys/A99W00-TRMC02-Y1WR36-K8JJ70-0BWR01

The Key Activation Info Structure

The Key activation info (activationInfo) structure holds information about activation of license key:

Field Name Field Type Description Interpretation on Input Interpretation on Output
activated JSON boolean Specifies whether this license key is already active (for example, when UID is optional) or activated (when UID is mandatory and a license was already activated). This is an informational field. Completely ignored on input. Always not null.
uid JSON string The UID used for activation.

If omitted, no actions.

If present:

  • If null, a license will be deactivated.
  • If not null, a license will be (re-)activated with the specified value.
 Null if no UID is currently assigned to a license key, otherwise - a non-null UID value.

Note: The key activation function is not supported in modern Plesk versions and is kept for backward compatibility.

The Key Item Structure

The Key item (key billable component) (item) is an auxiliary structure that holds information about a separate billable part of a license subscription:

Field Name Field Type Description Interpretation on Input Interpretation on Output
externalId JSON string The ID of a billable key component. This ID is external with respect to Key Administrator and Partner Central and is assigned to a license by a billing system.

If omitted, the value of this field is treated as null. The value will be stored on Key Administrator and Partner Central side.

The null value is permitted.

 The exact value stored on Key Administrator and Partner Central side is returned. May be null, if null is stored.
item JSON string

One of the following:

One of the following:

  • A Partner API 3.0 constant name.
  • Key type (base license name) or feature name for unmatched items.

Must not be omitted, null-valued, or empty (with no elements).

One of the following:

  • A Partner API 3.0 constant name.
  • Key type (base license name) or feature name for unmatched items.
quantity JSON string

The number of units or instances of a given option included with the license. Expressed as a natural number.

For example, the main product for a license is 360 Monitoring. The options are X sites and Y servers. Quantity must be specified for both options.

 The value of this field cannot be omitted and cannot be null. The value will be stored on Key Administrator and Partner Central side. The exact value stored on Key Administrator and Partner Central side is returned.

Example

An example response of the “Retrieving a License Key Structure” method:

{
"ownerId": "68746360",
"keyIdentifiers":

{ "keyId": 9467394, "keyNumber": "PLSK.09467394.0000", "activationCode": "AX1M00-2TGF09-FX0846-DA6K73-2VWY94", "activationLink": null }
,
"parentKeyIdentifiers": null,
"activationInfo": null,
"ipAddressBinding": null,
"nickname": "",
"productConfigurationId": 1708292,
"items": [

{ "externalId": null, "item": "PLESK-12-WEB-ADMIN-1M" }
],
"creationDate": "2022-05-30T06:54:37.450Z",
"lastModificationDate": "2022-05-30T09:25:43.534Z",
"updateDate": "2022-06-30T00:00:00.000Z",
"expirationDate": "2022-07-10T00:00:00.000Z",
"susExpirationDate": "2022-07-10T00:00:00.000Z",
"susStatus": "ACTIVE",
"supportExpirationDate": null,
"supportStatus": null,
"status": "ACTIVE",
"terminated": false,
"suspended": false,
"ownerSuspended": false,
"autoRenew": true,
"restrictIPBinding": false,
"frauds": [],
"lastReportingDate": "2022-05-30T20:29:42.987Z",
"lastReportingIp": "10.52.38.115",
"childKeyIdentifiers": [],
"overridingKeyIdentifiers": null
}